Skip to main content

System Architecture

High-level overview of the BankLingo platform architecture.

Overviewโ€‹

BankLingo is a modern, cloud-native core banking platform built on .NET 8 and Azure, featuring a sophisticated BPMN-driven process engine at its core. The system follows a layered architecture with clear separation of concerns and comprehensive integration capabilities.

Architecture Layersโ€‹

Layer Descriptionsโ€‹

1. Client Layerโ€‹

Purpose: User-facing applications that interact with the platform

  • Web Portal: React + TypeScript SPA for branch staff and administrators
  • Mobile Apps: Native iOS and Android apps for customers
  • External API Clients: Third-party integrations via REST API

Technology:

  • Frontend: React 18, TypeScript, Material-UI
  • State Management: Redux Toolkit
  • HTTP Client: Axios with interceptors

2. API Gateway Layerโ€‹

Purpose: Single entry point for all client requests

  • API Gateway: Azure API Management with request routing
  • Authentication: JWT tokens + TOTP (Time-based One-Time Password)
  • Rate Limiting: Throttling and quota management per client

Features:

  • Request/Response transformation
  • API versioning
  • Request validation
  • CORS handling
  • SSL/TLS termination

3. Application Layerโ€‹

Purpose: RESTful APIs exposing business functionality

  • Administration API: Core banking operations (deposits, loans, tellering)
  • NIBSS API: Interbank services (NIP, instant payments)
  • RexelPay API: Payment gateway operations
  • Core Banking API: Traditional banking operations

Technology:

  • .NET 8 Web API
  • ASP.NET Core MVC
  • Swagger/OpenAPI documentation
  • JSON serialization

4. Business Logic Layerโ€‹

Purpose: Process orchestration and business rule execution

  • BPM Core: Central process orchestration engine
  • Workflow Engine: BPMN 2.0 process execution
  • Business Rules: Decision tables and rule engine
  • Event Bus: Domain event publishing and subscription

Capabilities:

  • Dynamic process execution
  • Process versioning
  • Long-running workflows
  • Compensating transactions
  • Event-driven architecture

5. Process Engineโ€‹

Purpose: BPMN process interpretation and execution

  • Execution Engine: BPMN 2.0 interpreter
  • Context Loaders: Dynamic data resolution for process variables
  • Script Engine: JavaScript and C# script execution
  • Event Dispatcher: Entity event hub for domain events

Features:

  • Service tasks
  • User tasks
  • Script tasks
  • Gateways (Exclusive, Parallel, Inclusive)
  • Timer events
  • Message events
  • Subprocess support

6. Domain Layerโ€‹

Purpose: Core business domains and their logic

  • Deposits Module: Savings/current accounts, transactions
  • Loans Module: Loan origination, disbursement, repayment
  • Tellering Module: Branch operations, cash transactions
  • Vault Module: Branch vault, till management
  • Cheque Module: Cheque clearing, registration, stop payments
  • Book Register Module: Document and book management

Principles:

  • Domain-Driven Design (DDD)
  • Rich domain models
  • Domain events
  • Repository pattern
  • Unit of Work pattern

7. Data Layerโ€‹

Purpose: Persistent storage and caching

  • SQL Database: Azure SQL Database for transactional data
  • Redis Cache: Distributed cache for performance
  • Blob Storage: Documents, images, media files
  • Search Index: Azure Cognitive Search for full-text search

Data Strategy:

  • Write-through caching
  • Cache invalidation via events
  • Connection pooling
  • Optimistic concurrency
  • Audit logging

8. Integration Layerโ€‹

Purpose: External system integrations

  • NIBSS Integration: NIP (NIBSS Instant Payment), NEFT, RTGS
  • Payment Gateways: Card processing, POS transactions
  • Core Banking Systems: Integration with legacy systems
  • Notification Service: Email (SendGrid), SMS (Twilio), Push (Firebase)

Patterns:

  • Adapter pattern for integrations
  • Circuit breaker for resilience
  • Retry policies with exponential backoff
  • Idempotent message processing
  • Webhook support

9. Infrastructure Layerโ€‹

Purpose: Cross-cutting concerns and DevOps

  • Application Insights: Monitoring, logging, distributed tracing
  • Key Vault: Secrets and certificate management
  • Azure AD B2C: Customer identity and access management
  • Azure DevOps: CI/CD pipelines, automated testing

Features:

  • Centralized logging
  • Performance monitoring
  • Distributed tracing
  • Alert management
  • Secret rotation

Key Architectural Patternsโ€‹

1. BPMN-Driven Architectureโ€‹

All business processes are modeled in BPMN 2.0 and executed by the process engine. This provides:

  • Visual process documentation
  • Dynamic process modification without code changes
  • Process versioning
  • Audit trail of process execution

2. Event-Driven Architectureโ€‹

Domain events are published by entities and consumed by event handlers:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

3. Command Query Responsibility Segregation (CQRS)โ€‹

Separate paths for commands (writes) and queries (reads):

  • Commands: InitiateDepositCommand, ApproveDepositCommand
  • Queries: RetrieveDepositAccountQuery, GetTransactionListQuery

4. Repository Patternโ€‹

Data access abstraction:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

5. Unit of Work Patternโ€‹

Transactional consistency:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Technology Stackโ€‹

Backendโ€‹

  • .NET 8: Latest LTS framework
  • C# 12: Modern language features
  • ASP.NET Core 8: Web API framework
  • Entity Framework Core 8: ORM

Frontendโ€‹

  • React 18: UI library
  • TypeScript 5: Type-safe JavaScript
  • Material-UI: Component library
  • Redux Toolkit: State management

Databaseโ€‹

  • Azure SQL Database: Relational database (Premium tier)
  • Redis Cache: Distributed cache
  • Azure Blob Storage: Object storage

Cloud Services (Azure)โ€‹

  • App Services: Web hosting
  • API Management: API gateway
  • Application Insights: Monitoring
  • Key Vault: Secrets management
  • Azure AD B2C: Identity provider
  • Service Bus: Message queue
  • Azure DevOps: CI/CD

Third-Party Servicesโ€‹

  • NIBSS: Interbank services
  • SendGrid: Email delivery
  • Twilio: SMS delivery
  • Firebase: Push notifications

Communication Patternsโ€‹

1. Synchronous Communicationโ€‹

REST API (Client รขโ€ โ€ API Gateway รขโ€ โ€ Application Layer):

POST /api/bpm/cmd
{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountId": 12345,
    "amount": 50000,
    "tillId": 1
  }
}

2. Asynchronous Communicationโ€‹

Event Bus (Domain Layer รขโ€ โ€™ Event Handlers):

DepositMadeEvent รขโ€ โ€™ [
  UpdateBalanceEventHandler,
  NotifyCustomerEventHandler,
  UpdateStatisticsEventHandler
]

3. Process Communicationโ€‹

BPMN Workflow (Process Engine รขโ€ โ€™ Domain Layer):

Start รขโ€ โ€™ Validate Account รขโ€ โ€™ Debit Account รขโ€ โ€™ Credit Account รขโ€ โ€™ Notify Customer รขโ€ โ€™ End

Scalability Strategyโ€‹

Horizontal Scalingโ€‹

  • Stateless APIs: Scale App Services horizontally
  • Load Balancing: Azure Load Balancer + Traffic Manager
  • Database Scaling: Read replicas for query workloads

Vertical Scalingโ€‹

  • App Service Plans: Scale up during peak hours
  • Database Tiers: Premium P2 for production workloads

Caching Strategyโ€‹

  • Redis Cache: Frequently accessed data (account balances, user sessions)
  • CDN: Static assets (JavaScript, CSS, images)
  • Response Caching: API responses with Cache-Control headers

Security Architectureโ€‹

Authenticationโ€‹

  • JWT Tokens: Stateless authentication
  • TOTP: Two-factor authentication
  • Azure AD B2C: External identity provider

Authorizationโ€‹

  • Role-Based Access Control (RBAC): Branch Manager, Teller, Customer
  • Permission-Based: Granular permissions per operation
  • Branch-Level Security: Users can only access their branch data

Data Protectionโ€‹

  • Encryption at Rest: Transparent Data Encryption (TDE) for SQL
  • Encryption in Transit: TLS 1.3 for all communications
  • Key Management: Azure Key Vault for encryption keys

Complianceโ€‹

  • Audit Logging: All operations logged with user, timestamp, changes
  • Data Retention: Configurable retention policies
  • GDPR Compliance: Right to be forgotten, data portability

High Availabilityโ€‹

Databaseโ€‹

  • Geo-Replication: Secondary region for disaster recovery
  • Automatic Backups: Daily backups with 35-day retention
  • Point-in-Time Restore: Restore to any point in last 35 days

Applicationโ€‹

  • Multi-Region Deployment: Primary + Secondary Azure regions
  • Health Checks: Readiness and liveness probes
  • Automatic Failover: Traffic Manager routes to healthy region

Monitoringโ€‹

  • Application Insights: Real-time monitoring and alerting
  • Custom Alerts: CPU, Memory, Response Time, Error Rate
  • On-Call Rotation: PagerDuty integration for critical alerts

Performance Characteristicsโ€‹

Response Times (P95)โ€‹

  • Simple Queries: < 100ms
  • Complex Queries: < 500ms
  • Transaction Processing: < 1 second
  • Report Generation: < 5 seconds

Throughputโ€‹

  • API Requests: 1,000 requests/second
  • Transactions: 10,000 transactions/day
  • Concurrent Users: 500 users

Availabilityโ€‹

  • SLA: 99.9% uptime
  • RTO: 1 hour (Recovery Time Objective)
  • RPO: 5 minutes (Recovery Point Objective)

Deployment Architectureโ€‹

See Deployment Architecture for detailed Azure infrastructure topology.