API Gateway & Microservices
Relevant source files
The following files were used as context for generating this wiki page:
The BankChase project utilizes a high-performance, event-driven architecture that bridges a Next.js frontend/API gateway with specialized backend microservices. The system is designed to handle high-throughput banking operations, supporting up to 10,000+ transfers per second through a Go-based core server while maintaining strict security via an 8-layer security architecture.
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, RBAC_SYSTEM_ARCHITECTURE.md, README_START_HERE.md
System Architecture
The project employs a hybrid architecture where a Next.js frontend acts as the primary entry point and API gateway, managing initial request validation, rate limiting, and routing. Behind this gateway, the system splits into specialized microservices, including a Python FastAPI backend for general business logic and a high-performance Go Core Server for mission-critical transaction processing.
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, SETUP_COMPLETE.md, DELIVERY_SUMMARY.md
Service Overview
| Service | Technology | Primary Responsibility |
|---|---|---|
| API Gateway / Frontend | Next.js 16 | Request routing, Rate limiting, Auth validation, UI |
| General Backend | Python (FastAPI) | Auth, account management, webhooks, middleware |
| Core Banking Server | Go | High-performance transfers (10k/sec), ACID transactions |
| Cache Layer | Redis | Idempotency keys, rate limiting, session management |
| Persistence Layer | PostgreSQL & MongoDB | Immutable ledger, audit logs, transactions, notifications |
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, SETUP_COMPLETE.md, DELIVERY_SUMMARY.md
Request Flow and Service Interaction
The following diagram illustrates how a client request moves through the gateway to the specialized microservices and persistence layers.
The gateway ensures that all requests are validated for idempotency and rate-limited before reaching the internal services.
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, RBAC_SYSTEM_ARCHITECTURE.md
Core Microservices Implementation
Go Core Server (Production)
The Go server is the performance-optimized component of the microservice ecosystem. It handles high-concurrency banking operations and integrates directly with PostgreSQL for ACID-compliant ledger updates.
- Capabilities: 10,000+ transfers per second.
- Key Components: Connection pooling, structured logging, and middleware for auth and error handling.
- Endpoints: Includes
/api/transfers,/api/webhooks, and admin management interfaces.
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, SETUP_COMPLETE.md
Python FastAPI Backend (Business Logic)
The Python backend manages the broader application ecosystem, focusing on developer ergonomics and rapid integration of business features.
- Functionality: Lifespan management for connections, auth routes, and a webhook queue processor.
- Middleware: Implements
slowapifor rate limiting andasyncpgfor asynchronous database interactions.
Sources: SETUP_COMPLETE.md, PRODUCTION_BANKING_SERVER_COMPLETE.md
API Gateway Responsibilities
Security and Rate Limiting
The gateway layer enforces an 8-layer security architecture. It manages JWT token signing (HS256) and validation, ensuring that only authenticated requests reach the microservices. It also implements idempotency management to prevent duplicate transactions.
Microservice Endpoints Reference
| Endpoint | Method | Service | Description |
|---|---|---|---|
/api/auth/* | POST/GET | Python / Gateway | Registration, Login, 2FA, Password Resets |
/api/transfers/internal | POST | Go Server | Sub-100ms internal fund movement |
/api/transfers/international | POST | Go Server | Cross-border transfers via Currencycloud |
/api/customer/notifications | GET/PUT | Gateway / Mongo | Management of flexible notification data |
/api/admin/audit-logs | GET | Python / PG | Immutable forensic trail retrieval |
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, DELIVERY_SUMMARY.md, SYSTEM_STATUS_REPORT.md
Integration and Communication
Event-Driven Webhooks
The microservices communicate with external payment providers (like Paystack or Currencycloud) via secure webhooks. The gateway or specialized listeners verify these using HMAC-SHA256 signatures and timestamp validation.
- Signature Header:
X-SignatureorX-Paystack-Signature. - Verification: Validated against a shared secret to ensure authenticity from providers.
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, MONEY_TRANSFER_IMPLEMENTATION_SUMMARY.md
Hybrid Persistence Strategy
The microservice architecture supports a hybrid database approach to optimize for different data needs:
- PostgreSQL (ACID): Used for the transaction ledger, user roles (RBAC), and compliance data.
- MongoDB (Flexible): Used for high-volume, non-relational data like notifications, device tracking, and analytics.
Sources: DELIVERY_SUMMARY.md, README_START_HERE.md
Conclusion
The API Gateway and Microservices architecture in BankChase provides a scalable foundation for secure banking. By separating high-performance transaction logic (Go) from general business services (Python) and utilizing a Next.js gateway for centralized security enforcement, the system achieves enterprise-grade throughput and data integrity.
Sources: PRODUCTION_BANKING_SERVER_COMPLETE.md, DELIVERY_SUMMARY.md