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

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

View Architecture Diagram

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

Loading

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 X-HMAC header	200 OK 400 Bad Request 409 Conflict
POST	/collect	Initiate a UPI pull/collect request	Yes	HMAC-SHA256, required X-HMAC header	202 Accepted 400 Bad Request
GET	/transaction/{id}/status	Retrieve transaction status by ID	No	HMAC-SHA256, required X-HMAC header	200 OK 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 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 actions are logged with immutable trails; full replay possible.
• Extensibility: New rails and endpoints must conform to the base spec and pass regression coverage before merge.

---

Roadmap

Upcoming Phases

Phase	Branch / Feature	Core Deliverables	Why It Matters / Industry Mapping	Status
Phase 1 (MVP)	main, feature/advanced-tx-feat	Retry logic, DLQ, Idempotency, Audit trail, API rate-limiter, HMAC auth, → Webhook callbacks & Circuit Breaker	Bank-grade reliability, compliance (PCI-DSS/SOC2), production-grade rails	🟢 HERE
Phase 1.5 (Rails)	feature/rails-modules	Pluggable Cards, Wallets, Net-Banking, Crypto rails, BNPL & custom connectors	Unified infra for all payment methods, real aggregator power	🚧 Planned
Phase 2 (TestOps)	test/TestOps-performance_metrics, feature/advanced-api-hardening	Load & soak (1k+ TPS), chaos suite, mutation testing, advanced HMAC, replay/fraud resistance, edge-case certs	Stripe/AWS QA, Linux Foundation TestOps, zero-trust fintech	🚧 Planned
Phase 2.5 (Docs)	ship/documentation-suite, ship/e2e-documentation	Full enterprise-grade documentation: UML/sequence, ADRs, threat models, onboarding & forensic logs	Audit, onboarding, and compliance-grade docs for users & contributors	🚧 Planned
Phase 2.9 (OSSify)	ship/advanced-ossify	Badges, advanced PR/issue templates, CODEOWNERS, peer review, governance docs, code of conduct	Community trust, compliance, contributor culture	🚧 Planned
Phase 3 (DevOps)	feature/devops	Full CI/CD, Docker/Compose, release automation, supply-chain attestation	Prod-ready, auditable, cloud-deployable OSS	🚧 Planned
Phase 3.5 (IaC/Plat)	feature/iac-k8s-aws-deployment	Terraform, Helm, K8s manifests, RBAC, multi-cloud scripts	Cloud-native, vendor-neutral, SRE/Platform Engg. mapping	🚧 Planned
Phase 4 (SRE/Obs)	feature/sre-monitoring	Prometheus SLOs, Grafana dashboards, alerting, chaos engineering, cloud perf testing	Real SRE/observability, production monitoring & incident response	🚧 Planned
Release v3+	release/v3	Cloud-ready, Linux-grade, all rails/infra, SRE-complete	Fully auditable, production OSS—Linux Foundation class	🚧 Planned

---

Engineering Philosophy: Every branch solves a regulated production concern: security, reliability, audit, resilience, or governance. Structure is strictly modeled after Stripe, AWS, Linux Foundation, and PCI/SOC2 best practices—no ambiguity.

• Idempotency, Circuit Breaker, HMAC Auth, Audit Trail: Not just features—compliance-first controls as per open standards (RFCs, ISO, PCI-DSS).
• TestOps: Adversarial, not just “happy path.” Mutation, chaos, and soak by default.
• API Hardening: Replay resistance, input validation, and fraud-abuse defense for fintech trust.
• Documentation: Complete onboarding, regulatory, and audit evidence.
• OSS & Community: PR/issue hygiene, code of conduct, full transparency.
• Post-MVP: Real-world deployment (DevOps, IaC, SRE)—so the system is always ready for production scrutiny.

---

Idempotency & Reliability

Powered by enterprise-grade security and compliance to match Oracle-level standards.

FlossPay: Security, Reliability & Compliance Matrix

All features below are engineered for compliance-by-default, auditability, and absolute determinism. Controls are FLOSS-auditable; no “checkbox” security or black-box behaviors.

Control Area	Mechanism & Enforcement	Standard / Reference	Status
Idempotency	Idempotency-Key: <uuid4> required per operation. UUIDv4 (cryptographically random), validated per RFC 4122. Replay resistance enforced via HMAC (RFC 2104), TTL-governed.	RFC 4122, RFC 2104	Shipped / Active
Retry & DLQ	Exponential backoff (2¹...2⁵ sec), 5-attempt cap; persistent failure results in atomic DLQ move (transactions.dlq). Jitter source: FIPS 140-2 PRNG.	FIPS 140-2	Shipped / Active
Circuit Breaker	service_circuit_breakers (PostgreSQL) table monitors 3rd-party dependency state; threshold-triggers, audit vault, auto-resets. ISO 27001 mapped.	ISO 27001	Planned / In-Progress
Rate Limiting	Token bucket per client_id, quotas persisted in client_rate_limits. OAuth 2.0-compatible scopes (RFC 6749); all rate changes auditable via immutable ledger.	RFC 6749, PCI DSS	Shipped / Active
Audit Trail	Immutable INSERT ONLY partitions (PostgreSQL); all state changes signed with SHA-256 (FIPS 180-4), logs shipped to encrypted ELK stack.	FIPS 180-4, PCI DSS	Shipped / Active
Data Encryption	All sensitive data AES-256-GCM encrypted at rest; key management by AWS KMS or on-prem HSM. 3DS, PCI DSS v4.0 ready.	AES-GCM, PCI 3DS	Shipped / Active
Transport Security	Enforced TLS 1.3 (RFC 8446); mutual TLS optional; HMAC-SHA256 (RFC 4868) signatures on all external API.	RFC 8446, RFC 4868	Shipped / Active
Compliance & Monitoring	PCI-DSS L1, SOC 2 controls. Telemetry via Prometheus; critical anomaly & DLQ backlog paging via PagerDuty.	PCI DSS, SOC 2	Shipped / Active
Governance & Review	CIS Benchmarks in CI; quarterly independent pen tests, full findings published; all PRs/merges signed & traceable.	CIS, OSS Review Board	Shipped / Active
Webhooks / Callbacks	Outbound event notification, signed and tracked; retry with backoff; full delivery and attempt ledger; API contracts public.	REST, HMAC-SHA256	Planned / RFC in Review
MVP Coverage	All above except Circuit Breaker and Webhook are audited, tested, and locked in current MVP; planned features marked.	—	Shipped / MVP

---

Note:

• Features labeled Planned are under active RFC/implementation in public branches.
• No features depend on proprietary middleware; all controls are peer-auditable and align with Linux Foundation/Oracle-level auditability.
• Webhooks/circuit-breakers will be backward-compatible, spec-driven, and never vendor-locking.

---

References hyperlinked. Each control and mechanism is FLOSS-auditable, designed to withstand financial regulatory review and security pen-test scrutiny.

---

Getting Started

1. Clone & Bootstrap

   git clone https://github.com/flosspay/flosspay.git && cd flosspay
   ./mvnw verify -Pdev

2. Provision PostgreSQL & Redis

   # PostgreSQL
   psql -U postgres -c "CREATE DATABASE flosspay_db;"
   psql -U postgres -c "CREATE USER flosspay_user WITH PASSWORD 'secret';"
   psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE flosspay_db TO flosspay_user;"
   
   # Redis (Memurai or redis-stack)
   redis-cli ping  # -> PONG

3. Run All Services (Dev Mode)

   ./scripts/dev-up.sh   # spins api-service, worker-service, postgres, redis via Docker Compose

---

---

TestOps

TestOps, Performance Metrics & Auditing

Focus Area	Branch (TestOps/---)	Deliverable / Action	Industry Benchmark / Standard	How It Signals Production Readiness
Unit Testing	TestOps/unit	85%+ branch/mutation coverage (PIT); strict CI gate	Stripe/Oracle: “green bar” required	Prevents regressions at code-level; enforces safety
Integration Testing	TestOps/integration	Testcontainers: boot Postgres+Redis, full API↔worker↔DB flows	AWS/Uber: live DB+queue in CI	Proves real service, DB, and queue integration
E2E Scenarios	TestOps/e2e	Gatling/k6: /pay→/status, /collect→/status, retry+DLQ+timeout	PayPal/Stripe: payment edge QA	Simulates real user & failure edge-cases
Performance Testing	TestOps/performance_metrics	Load/soak: 100–1,000 TPS; latency, error rates logged (CI or local)	AWS: cloud perf/SRE pipelines	Certifies scale: “cloud-ready” throughput
Mock Services	TestOps/mocks	Deterministic mocks: UPI, NPCI, 3rd-party rails; error & chaos injection	Fintech: “blast radius”/failure test	Guarantees failover, never silent fail
Edge Case Tracking	TestOps/issues	Every regression/non-happy-path scenario tracked & test-locked	Google: post-mortem QA discipline	“No unexplained bugs”—all failures are accounted for
Advanced Error	TestOps/error_handling	DLQ/circuit breaker simulation, alerting/telemetry flows	PCI-DSS/SOC2: financial compliance	No data loss on fail; audit & alert tested
Observability	TestOps/observability	Prometheus metrics, Grafana dashboards, alert configs	SRE: cloud-native monitoring	SLOs and error rates are test-verified

---

How This Works in this Flow Works

• Every PR: Must pass all TestOps suites (CI-enforced).

• Performance results: (TPS, latency, error) can be generated and plugged into SRE dashboards.

• Block on test failure: No unvetted code reaches main.

• How to Run:

  ./mvnw verify -PTestOps
  ./scripts/run-e2e.sh
  k6 run TestOps/performance_metrics/pay_and_collect_flow.js

• Metrics: Ready for Grafana/Prometheus (sample configs in TestOps/observability/).

---

Production Readiness

Capability	Implementation & Controls	Industry Benchmark / Reference
Configuration & Secrets	Spring Cloud Config (centralized), AWS KMS/HashiCorp Vault: All secrets encrypted at rest & in transit; zero plaintext anywhere	Linux Foundation, PCI-DSS, AWS SSM, GCP Secret Manager
Observability & Tracing	Micrometer → Prometheus → Grafana dashboards; OpenTelemetry/Sleuth for full request/trace ID propagation; log ship to ELK	CNCF, SRE Book, Stripe SLO discipline
Security Screening	OWASP Dependency-Check CI gate; auto-fail on CVEs; strict JPA parameter binding (SQLi); TLS 1.3 only (RFC 8446); HMAC on all APIs	OWASP Top 10, PCI-DSS, Oracle Secure Coding
Compliance & Audit	PCI-DSS v4 tokenization, immutable audit logs (Postgres partitions, signed with SHA-256), SOC 2 mapped controls, quarterly pen-test	PCI-DSS v4, SOC 2, ISO 27001
Scalability & Cloud	Horizontal scaling (K8s manifests/Helm); stateless worker groups; zero downtime deploys; rolling upgrades; AWS/GCP/Azure ready	Kubernetes, CNCF, AWS Well-Architected, Uber

---

Production Philosophy:

• No plaintext secrets, ever.
• Zero tolerance for silent errors or missed alerts—every trace is logged and measurable.
• Security is baked-in, not bolted-on—every commit, every pipeline.
• Compliance is active—audit logs, pen-test cadence, and config management by code.
• Scaling is native—infra is ready for real-world loads, cloud or on-prem, zero lock-in.

---

Contributing

Step	Requirement / Control
1. Fork & Branch	Fork the repo; create a branch: feature/<topic> or fix/<ticket#> (strict convention).
2. Local Checks	Run ./scripts/pre-commit.sh (lint, static analysis, unit/integration tests, security scan).
3. Pull Request	Open a PR to main. PRs must pass all CI checks and receive core maintainer review.
4. Automated CI/CD	GitHub Actions enforce lint, test, coverage, and security gates; manual merges are disallowed.
5. Staging Deploy	All merges auto-deploy to staging for peer validation before production.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for full governance, branching, and review policies.

By contributing, you agree to the FLOSS code of conduct and compliance requirements.

---

Community & Security

Channel	Purpose
GitHub Issues	File bugs, feature requests, or regression reports.
GitHub Discussions	Architecture Q&A, RFC proposals, roadmap debate.
Security Contact	Report vulnerabilities: [email protected] (GPG key in repo, 24h triage SLA).

---

📚 Documentation Suite (Enterprise Roadmap)

FlossPay will provide a full enterprise-grade documentation suite for production and compliance use. Only the most critical docs are included in this MVP; the remainder will roll out as the community and users require.

Document / Guide	Status	Description / Purpose
JavaDoc (Inline)	✅ Complete	All public classes/methods fully documented for developersinstructions
Quickstart Guide	✅ Complete	Fast local setup, run, and test instructions
Architecture Overview	✅ Complete	Diagrams and text for system modules, flows, and data paths
OpenAPI Specification	✅ Complete/⏳	API contract (YAML/Swagger UI)
Performance Benchmarks	⏳ Planned	k6/Gatling test results, load & latency measurements
Architecture Decision Records (ADR)	⏳ Planned	Rationale for tech/design choices (e.g., Redis Streams, audit)
Threat Model & Security Guide	⏳ Planned	Attack surface, mitigations, compliance mapping
Contributor Handbook	⏳ Planned	Dev onboarding, workflow, branch/pull process
Forensic Logging Guide	⏳ Planned	Audit log format, replay, compliance trace
API Usage Examples	⏳ Planned	cURL/HTTPie walkthroughs, sample requests/responses
FAQ & Troubleshooting	⏳ Planned	Common issues, fixes, and operational advice

---

MVP note: > To ship fast, only Quickstart, Architecture, and OpenAPI are fully delivered today. All other enterprise docs are on the public roadmap and will be released as prioritized by user and contributor demand.

---

License & Maintainers

License	MIT License
Project Owner	David Grace – Founder & Chief Architect
Core Maintainer	David Grace
Product Manager, Branding & Launch Strategy	Goutham @gouthamdev

For sponsorship, collaboration, or professional engagement: Open an Issue or Discussion with your context and intent. All outreach is reviewed under FLOSS and compliance standards.

---

This repo is governed at Linux Foundation discipline: No unreviewed code, no silent merges, no black-box features. Contact Owner for all critical matters.