/$$$$$$$$/$$                              /$$$$$$$
                | $$_____/ $$                             | $$__  $$
                | $$     | $$  /$$$$$$   /$$$$$$$ /$$$$$$$| $$  \ $$/$$$$$$  /$$   /$$
                | $$$$$  | $$ /$$__  $$ /$$_____//$$_____/| $$$$$$$/____  $$| $$  | $$
                | $$__/  | $$| $$  \ $$|  $$$$$$|  $$$$$$ | $$____/ /$$$$$$$| $$  | $$
                | $$     | $$| $$  | $$ \____  $$\____  $$| $$     /$$__  $$| $$  | $$
                | $$     | $$|  $$$$$$/ /$$$$$$$//$$$$$$$/| $$    |  $$$$$$$|  $$$$$$$
                |__/     |__/ \______/ |_______/|_______/ |__/     \_______/ \____  $$
                                                                             /$$  | $$
                                                                            |  $$$$$$/
                                                                             \______/

<!--<p> <a href="https://github.com/gracemann365/FlossPay/blob/main/LICENSE"> <img alt="License: MIT" src="https://img.shields.io/github/license/Gracemann365/flosspay?logo=opensourceinitiative" /> </a> </p> -->

FlossPay is a Kernel-inspired, enterprise-grade Free/Libre Open-Source payments aggregator. Modeled after Linux’s rigorous governance (meritocratic maintainership, strict code review, transparent changelogs) and Oracle Financials audit-first architecture (immutable ledgers, compliance-ready schemas), FlossPay delivers bank reliability to indie merchants, MSMEs, and developers. With a community-driven ethos, FlossPay removes barriers and empowers small businesses with open, transparent infrastructure.

Current Rail Availability: v0.2-alpha offers a hardened UPI rail, fully tested and validated; downstream rails (cards, wallets, net-banking) are tracked via stable branches and will not affect core stability.

---

Vision & Mission

Vision

Empowers indie merchants, MSMEs, and developers with Payment infrastructure which is Open, Transparent, and Accessable.

Mission

Deliver an Auditable, Modular, Self-hostable payments platform that delivers Bank-Grade Reliabilitys while remaining FLOSS.

---

⚠️ Legal Notice

This software is provided “AS IS” and “AS AVAILABLE” — with NO WARRANTY of any kind.

By accessing, using, modifying, or distributing this project, you AGREE that:

• The authors and contributors are NOT liable for any damages, legal issues, or regulatory actions (direct or indirect) arising from any use of this software.
• This project is for educational and template purposes ONLY.
  Any commercial, financial, or production use is 100% at your own risk.
• If you use this software in any operational, production, or commercial context, you are solely responsible for all legal, regulatory, and compliance obligations—US, EU, and international.
• See LICENSE for full terms.

If you do NOT agree to these terms, do NOT use or access this codebase.

---

Table of Contents

1. Vision & Mission
2. Solution Architecture
3. Project Structure
4. Domain Model
5. API Reference
6. Roadmap⚡ Know Where We Stand ⚡
7. Idempotency & Reliability
8. Getting Started
9. Production Readiness
10. TestOps , Performance Metrics & Auditing
11. Contributing
12. 📚 Documentation Suite (Enterprise Roadmap)
13. Community & Support
14. License & Maintainers

---

Solution Architecture

<details> <summary>View Architecture Diagram</summary>

flowchart TD
  subgraph Client Tier
    Merchant["Merchant App"]
  end
  subgraph FlossPay Core
    API["API Service"]
    Worker["Worker Service"]
    Stream["Redis Streams \"transactions.*\""]
    DB[("PostgreSQL Ledger")]
  end
  subgraph Observability
    Grafana["Grafana + Prometheus"]
  end

  Merchant -->|REST: /pay, /collect| API
  API -->|XADD| Stream
  Stream -->|XREADGROUP| Worker
  Worker -->|UPDATE| DB
  API -->|SELECT| DB
  DB -->|metrics| Grafana

</details>

Key Principles

• Modularity: Clear service contracts for scalability.
• Async Resilience: Failure-isolated pipelines via Redis Streams.
• Auditability: Immutable ledger with SHA-256 checksums.

---

Project Structure

| Module | Responsibility | Key Technologies | | ---------------- | ------------------------------------------------------ | ----------------------------------- | | api-service | Public REST API, OpenAPI spec, validation, idempotency | Spring Boot 3.x, Java 21 | | worker-service | Async processing, retries, DLQ, webhook emit | Java 21, Spring Boot, Redis Streams | | shared-libs | DTOs, validation, exception hierarchy | Java Module System | | docs | UML diagrams, ADRs, system design, benchmarks | Asciidoc, PlantUML | | ops | Docker, Helm, Terraform, GitHub Actions | DevOps Stack |

---

Domain Model

| Entity | Purpose | Core Fields | | ----------------------- | --------------------------- | --------------------------------------------------- | | Transaction | Generic payment intent | id · amount · currency · method · status | | TransactionHistory | Lifecycle state changes | txn_id · status_from · status_to · timestamp | | PaymentMethod | Supported rails enum | UPI · CARD · WALLET · NETBANKING | | CardTransaction | Card-specific data | pan_token · expiry · scheme | | WalletTransaction | Wallet-specific data | wallet_id · provider | | IdempotencyKey | Guarantees at-most-once | key · owner · expiry | | WebhookEvent | Outbound notifications | id · type · payload · retries | | WebhookCallback | Tracks delivery & retries | callback_id · txn_id · url · status · attempts | | ServiceCircuitBreaker | Monitors 3rd-party services | service_name · state · failure_count · last_failure | | ClientRateLimit | API quota state | client_id · tokens · last_refill |

---

API Reference

Scope: This release exposes only foundational payment and health endpoints. All other interfaces are under active RFC and subject to review.

Base Path: /api/v1

---

| Method | Endpoint | Description | Idempotent | AuthN / AuthZ | Response Codes | | ------ | -------------------------- | ----------------------------------- | ---------- | ---------------------------------------- | ----------------------------------------- | | POST | /pay | Initiate a UPI push payment | Yes | HMAC-SHA256, required<br>X-HMAC header | 200 OK<br>400 Bad Request<br>409 Conflict | | POST | /collect | Initiate a UPI pull/collect request | Yes | HMAC-SHA256, required<br>X-HMAC header | 202 Accepted<br>400 Bad Request | | GET | /transaction/{id}/status | Retrieve transaction status by ID | No | HMAC-SHA256, required<br>X-HMAC header | 200 OK<br>404 Not Found | | GET | /health | Liveness check (simple ping) | N/A | No Auth (public) | 200 OK | | GET | /health/ready | Readiness check (system ready) | N/A | No Auth (public) | 200 OK<br>503 Service Unavailable |

---

Authentication

• All payment endpoints require HMAC-SHA256-based authentication.

  • Client must sign the canonical request and set: X-HMAC: <Base64 signature>
  • Idempotency enforced via Idempotency-Key header (required, unique per request).

Content Negotiation

• Content-Type:

  • All requests and responses: application/json

• Versioning:

  • All endpoints are namespaced under /api/v1 (future-proofing).

Health Endpoints

• /health

  • Stateless liveness probe; always returns "liveness Check : Im Alive" on 200 OK.

• /health/ready

  • Readiness probe; returns "READY" on 200 OK (future: returns 503 if dependencies unavailable).

Standardization & Compliance

• All endpoints and headers are documented in the OpenAPI 3.1 specification.
• API is designed for extension with additional rails (card, wallet, net-banking) via pluggable modules.
• Security-first: All authentication and error flows are explicitly logged and traceable (PCI-DSS/SOC2-ready).

---

Example: /pay Request

curl -X POST http://localhost:8080/api/v1/pay \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-280" \
  -H "X-HMAC: <your-signature-here>" \
  -d '{"senderUpi": "flossalice@upi", "receiverUpi": "flossbob@upi", "amount": 28.00}'

Swagger/OpenAPI UI is available at /swagger-ui.html for live contract validation.

---

Principles:

• Transparency: All behaviors, errors, and flows are deterministic and documented.
• Interoperability: Headers, request/response codes, and conventions follow industry standards for maximum compatibility.
• Auditability: All action