System Architecture
This document describes Lana's system architecture, including layers, components, and data flow.
System Layer Overview
Lana follows a layered architecture that separates concerns and enables maintainability:
Client Layer
Admin Panel
Web application for bank operations:
- Customer management
- Credit administration
- Financial reports
- Configuration
External Customer Clients
Customer-facing applications are developed outside this repository and consume the customer-server GraphQL API with Keycloak access tokens from the customer realm. lana-mobile-demo is the reference external client — keep it in mind when changing the customer-server API, the customer realm, or the app.{domain} route.
Identity Layer
Keycloak (Port 8081)
Identity and access management:
- Two realms:
adminandcustomer - OAuth 2.0 / OpenID Connect
- User authentication and session management
- Token signing keys exposed through realm JWKS endpoints
Application Layer
admin-server
GraphQL API for administrative operations:
- Full system access
- RBAC-based authorization
- Connects to admin Keycloak realm
customer-server
GraphQL API for customer operations:
- Limited scope to customer's own data
- Simplified interface
- Connects to customer Keycloak realm
lana-cli
Command-line tool for:
- Starting servers
- Running migrations
- Administrative tasks
- Batch operations
lana-app
Central business logic orchestrator:
- Initializes all domain services
- Coordinates cross-domain operations
- Manages application lifecycle
Domain Layer
Implements core business logic using Domain-Driven Design:
| Domain | Purpose |
|---|---|
| Customer | Customer lifecycle and KYC |
| Credit | Credit facilities and disbursements |
| Deposit | Deposit accounts and withdrawals |
| Governance | Multi-party approval workflows |
| Accounting | Financial period management |
Infrastructure Layer
PostgreSQL
Primary data store:
- Event storage
- Entity state
- Audit logs
Cala Ledger
Double-entry accounting system:
- Account hierarchy
- Transaction recording
- Balance calculation
External Integrations
- BitGo/Komainu: Cryptocurrency custody
- Sumsub: KYC verification
- SMTP: Email notifications
Data Flow
Request Processing
Event Flow
Key Architectural Decisions
Event Sourcing
All state changes are captured as events:
- Complete audit trail
- Temporal queries
- Event replay capability
Hexagonal Architecture
Clean separation of concerns:
- Domain logic isolated from infrastructure
- Adapter pattern for external services
- Testable business logic
CQRS Pattern
Command Query Responsibility Segregation:
- Optimized read paths
- Separate write operations
- Eventual consistency where appropriate