Cartera Financial OS

Cartera is a production-grade, event-driven, fault-tolerant financial operating system. It demonstrates production patterns for high-throughput, resilient financial transaction processing using a Java 21 / Spring Boot 3.3.x microservices backend and a Flutter cross-platform frontend.

Inspired by enterprise payment systems like Stripe, Cartera incorporates microservices choreography, asynchronous event streaming with Apache Kafka, immutable double-entry ledger bookkeeping, connection pooling with PgBouncer, distributed caching/idempotency locking with Redis, custom core financial algorithms (CASCADE, CORTEX, RAPID, REFLUX, ROLLBACKX), Razorpay payment handling (https://razorpay.me/@cartera), and a modern, premium mobile experience.

---

5 Custom Core Algorithm Engines (Author: Om Ghante)

Cartera implements 5 proprietary algorithms engineered specifically for high-concurrency, resilient financial operations:

1. CASCADE Vector-Clock CRDT Balance Engine (wallet-service):

   • Lock-free, causal vector-clock balance merges for shared and family wallets. Replaces pessimistic SELECT FOR UPDATE locks and guarantees zero-overdraft preconditions.

2. CORTEX Adaptive Resilience Engine (common-lib):

   • Composite Pressure Score (CPS) driven adaptive circuit breaking and priority-based request shedding (P1_CRITICAL through P5_BACKGROUND). Prevents recovery storms under heavy load.

3. RAPID Multi-Wallet Allocation Solver Engine (wallet-service):

   • Constraint-propagation + branch & bound solver for multi-wallet deposit splits (POST /api/v1/wallets/allocate). Automatically distributes incoming deposits across monthly expense budgets, goal deficits, and emergency savings.

4. REFLUX Crash Recovery Engine (ledger-service):

   • Dependency-aware selective Kafka event replay on application startup (ApplicationReadyEvent). Prunes intermediate dead writes for ~47% faster crash recovery.

5. ROLLBACKX Deployment Health Gate Engine (common-lib):

   • Canary deployment health gate algorithm evaluating live canary metrics (P99 latency > 500ms, ledger error rate > 0.5%, heap > 90%) to trigger automated rollbacks in < 60 seconds.

---

Architecture Overview

graph TD
    %% Client Layer
    Flutter[Flutter Mobile Client] -->|HTTP / SSE| Gateway[API Gateway :8080]

    %% Microservices Service Discovery
    Gateway -->|Routes Requests| Discovery[Eureka Service Registry :8761]

    %% Gateway to Microservices Routing
    Gateway --> Identity[Identity Service :8081]
    Gateway --> Wallet[Wallet Service :8082]
    Gateway --> Ledger[Ledger Service :8083]
    Gateway --> Dashboard[Dashboard Service :8084]
    Gateway --> Analytics[Analytics Service :8085]
    Gateway --> Audit[Audit Service :8086]
    Gateway --> Delegation[Delegation Service :8087]
    Gateway --> Mandate[Mandate Service :8088]

    %% Event Stream & Cache Backplanes
    Wallet <-->|Idempotency / Cache| Redis[(Redis :6385)]
    Ledger <-->|Idempotency / Cache| Redis
    
    Wallet -.->|Publishes Events| Kafka[[Apache Kafka :9095]]
    Ledger -.->|Publishes/Consumes Events| Kafka
    Audit -.->|Consumes Audit Events| Kafka
    Analytics -.->|Consumes Spending Events| Kafka
    Mandate -.->|Publishes Scheduled Payments| Kafka

    %% Dedicated DB Databases per Service
    Identity --->|Per-Service DB| DB[(PostgreSQL + PgBouncer :5435/6435)]
    Wallet --->|Per-Service DB| DB
    Ledger --->|Per-Service DB| DB
    Analytics --->|Per-Service DB| DB
    Audit --->|Per-Service DB| DB
    Delegation --->|Per-Service DB| DB
    Mandate --->|Per-Service DB| DB

Loading

---

Detailed Component Breakdown

1. Backend Microservices (/services)

Built with Java 21 and Spring Boot 3.3.x, featuring Spring Cloud ecosystem integrations:

• Eureka Server (eureka-server): Service discovery registry on port 8761.
• API Gateway (api-gateway): Reactive entry point on port 8080 with JwtAuthFilter validating HS256 tokens and injecting X-User-Id downstream headers.
• Identity Service (identity-service): Google Sign-In verification, user onboarding, JWT token rotation, and Cartera PIN authorization.
• Wallet Service (wallet-service): Multi-type digital wallets (Personal, Expense, Goal, Savings, Shared). Features Redis cache-aside balance reads, Razorpay payment order/webhook signature verification (https://razorpay.me/@cartera), Fraud Detection sliding window velocity controls (max 10 txns/min), CASCADE CRDT balance engine, and RAPID fund allocation solver.
• Ledger Service (ledger-service): Immutable double-entry ledger bookkeeping. Evaluates REFLUX crash recovery on startup and provides paginated transaction search.
• Dashboard Service (dashboard-service): BFF orchestrator aggregating user wallets, insights, and low-balance alert generation in parallel using CompletableFuture.allOf().
• Analytics Service (analytics-service): Monthly category spend aggregation, MoM +30% spike warnings, and goal milestone alerts (25%, 50%, 75%, 100%).
• Audit Service (audit-service): Async audit listener logging events to audit_db and executing automated 6-hour cron balance invariant reconciliation checks.
• Delegation Service (delegation-service): Temporary wallets, claim tokens, system holding account locks, expiry auto-refunds, and family allowances.
• Mandate Service (mandate-service): Scheduled recurring payment processing with 3-strike failure pausing.
• Common Library (common-lib): CORTEX resilience engine, ROLLBACKX health gate, shared DTOs, events, exceptions, and Kafka topic definitions.

---

Local Development & Quick Start

Prerequisites

• Java Development Kit (JDK) 21
• Docker & Docker Compose
• Maven 3.9+ (or use repository ./mvnw)

1. Launch Docker Infrastructure & Databases

export POSTGRES_PASSWORD=postgres
docker compose -f infrastructure/docker/docker-compose.yml up -d

2. Run Test Suite

./mvnw test

3. Launch Microservices

export POSTGRES_PASSWORD=postgres
./scripts/backend.sh start

4. Check Status

./scripts/backend.sh status

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2026 Om Ghante