FlowLedger 💸

FlowLedger is a modern, event-driven, double-entry bookkeeping financial application. It allows users to create accounts, transfer money securely, and view a perfectly balanced ledger of all their transactions.

Built with scalability and data integrity in mind, FlowLedger leverages Apache Kafka for asynchronous transaction processing and Redis for strict idempotency to guarantee that no duplicate transactions occur.

---

📸 Screenshots

Here are screenshots and diagrams from the project (paths are workspace-relative):

• 
• 
• 
• 

---

✨ Features

• Double-Entry Bookkeeping: Every transfer creates a strictly balanced DEBIT and CREDIT entry in the ledger.
• Event-Driven Architecture: High-throughput transaction processing using Apache Kafka.
• Idempotency Guarantee: Uses Redis SETNX to intercept and reject duplicate API requests, ensuring money is never double-spent.
• Secure Authentication: Stateless JWT-based authentication with Spring Security and Role-Based Access Control (RBAC).
• Comprehensive Dashboard: View recent transactions, total balances, and account summaries at a glance.
• Detailed Transaction History: Paginated and filterable (by type and status) transaction history.
• Modern UI: Responsive, fast, and beautifully styled frontend using React, Vite, and Tailwind CSS.

---

🏗 Tech Stack

Frontend

• Framework: React 19 + Vite
• Styling: Tailwind CSS 4
• Routing: React Router DOM
• Icons: Lucide React
• HTTP Client: Axios

Backend

• Core: Java 21 + Spring Boot 3.5.14
• Security: Spring Security + JJWT (JSON Web Tokens)
• Database: MySQL + Spring Data JPA (Hibernate)
• Message Broker: Apache Kafka + Zookeeper
• Caching & Idempotency: Redis

---

🗺 System Architecture

High-Level Architecture

Sequence & Flow Diagrams

Database Entity-Relationship Diagram (ERD)

Accounting Principle Illustration

---

🚀 Getting Started

Prerequisites

Make sure you have the following installed:

• Java 21
• Node.js (v18+)
• Docker & Docker Compose (For running MySQL, Kafka, Zookeeper, and Redis)
• Maven

1. Start Infrastructure (Docker)

The project includes a docker-compose.yml file to spin up all required databases and brokers.

cd backend
docker-compose up -d

This will start MySQL (3306), Redis (6379), Kafka (9092), and Zookeeper (2181).

2. Start the Spring Boot Backend

Navigate to the backend directory and run the Spring Boot application:

cd backend
./mvnw spring-boot:run

The backend will run on http://localhost:8080.

3. Start the React Frontend

Open a new terminal, navigate to the frontend directory, install dependencies, and start the Vite dev server:

cd frontend
npm install
npm run dev

The frontend will be accessible at http://localhost:5173.

---

🔀 Transaction Flow & Idempotency

FlowLedger uses a highly resilient flow for processing financial transfers:

1. Idempotency Check: The user initiates a transfer. An IdempotencyFilter checks Redis for the unique request key. If it exists, the request is rejected immediately (409 Conflict). If it's new, it is saved for 24 hours.
2. Validation: The TransactionService validates account ownership, active statuses, and sufficient funds.
3. Event Publishing: A PENDING transaction is saved to MySQL, and a TransferEvent is published to Kafka. The user immediately receives a success response.
4. Asynchronous Processing: The Kafka Consumer picks up the event, executes the transfer, creates exact DEBIT and CREDIT LedgerEntry records, and updates the transaction status to POSTED.

[Image: Sequence Diagram of Transaction Flow]

[Image: Double-Entry Bookkeeping Flowchart]

---

📚 API Endpoints Summary

Authentication (/api/auth)

• POST /register - Register a new user
• POST /login - Authenticate and receive JWT

Accounts (/api/accounts)

• POST / - Create a new account
• GET /my-accounts - Fetch all accounts for the authenticated user
• GET /{id}/balance - Get balance for a specific account

Transactions (/api/transactions)

• POST /transfer - Initiate a money transfer (Requires Idempotency-Key header)
• GET /history - Get paginated/filtered transaction history
• GET /recent - Get top 5 recent transactions

Ledger (/api/ledger)

• GET /entries - Get paginated DEBIT/CREDIT ledger entries
• GET /balance-verification - Verify that total Debits = total Credits across all transactions

---