Skip to main content

Component Architecture

Overviewโ€‹

BankLingo's component architecture follows a modular, domain-driven design with clear separation of concerns. The system is organized into functional modules that encapsulate business logic, data access, and API boundaries.

High-Level Component Diagramโ€‹

Module Dependenciesโ€‹

Administration Moduleโ€‹

Purpose: Core administration and system management

Dependencies:

  • Process Engine (BPMN execution)
  • Transaction Management (universal commands)
  • Audit Service (compliance tracking)

Key Components:

  • User Management
  • Branch Management
  • Product Configuration
  • System Settings
  • Authorization Engine

API Endpoints: /api/bpm/*, /api/admin/*

Deposits Moduleโ€‹

Purpose: Deposit account and transaction management

Dependencies:

  • Transaction Management (deposit/withdrawal transactions)
  • Accounting Services (GL posting)
  • Process Engine (workflow automation)
  • Notification Service (customer alerts)

Key Components:

  • Deposit Account Lifecycle
  • Transaction Processing (Deposits/Withdrawals)
  • Interest Calculation
  • Fee Management
  • Account State Management

API Endpoints: /api/bpm/cmd (deposit commands)

Domain Entities:

  • DepositAccount
  • DepositTransaction
  • DepositProduct
  • DepositProductAccountingRule

Loans Moduleโ€‹

Purpose: Loan account and transaction management

Dependencies:

  • Transaction Management (loan transactions)
  • Calculation Services (interest, amortization)
  • Accounting Services (GL posting)
  • Process Engine (approval workflows)

Key Components:

  • Loan Account Lifecycle
  • Loan Disbursement
  • Repayment Processing
  • Loan Reschedule/Refinance
  • Arrears Management
  • Loan Write-off

API Endpoints: /api/bpm/cmd (loan commands)

Domain Entities:

  • LoanAccount
  • LoanTransaction
  • LoanProduct
  • LoanSchedule

Tellering Moduleโ€‹

Purpose: Teller operations and till management

Dependencies:

  • Transaction Management (teller transactions)
  • Vault Module (cash transfers)
  • Deposits Module (account operations)
  • Cheque Module (cheque processing)

Key Components:

  • Till Management (Open/Close)
  • Cash In/Cash Out
  • Teller Transactions
  • Till Reconciliation
  • Cheque Clearing

API Endpoints: /api/bpm/cmd (teller commands)

Domain Entities:

  • TellerTill
  • TellerTransaction
  • CashTransaction

Vault Moduleโ€‹

Purpose: Branch vault and cash management

Dependencies:

  • Transaction Management (vault transactions)
  • Tellering Module (till funding)
  • Accounting Services (cash GL)

Key Components:

  • Branch Vault Management
  • Vault Funding
  • Till-to-Vault Transfers
  • Cash Position Tracking

API Endpoints: /api/bpm/cmd (vault commands)

Domain Entities:

  • BranchVault
  • VaultTransaction
  • CashPosition

Cheque Moduleโ€‹

Purpose: Cheque registration and clearing

Dependencies:

  • Transaction Management (cheque transactions)
  • Deposits Module (account updates)
  • Tellering Module (teller processing)

Key Components:

  • Cheque Book Registration
  • Cheque Deposits
  • Cheque Withdrawals
  • Cheque Clearing
  • Cheque Bouncing/Cancellation

API Endpoints: /api/bpm/cmd (cheque commands)

Domain Entities:

  • ChequeRegistration
  • ChequeClearingTransaction
  • ChequeBook

Cross-Cutting Componentsโ€‹

Process Engineโ€‹

Purpose: BPMN workflow execution and automation

Responsibilities:

  • BPMN 2.0 process execution
  • User task management
  • Gateway evaluation
  • Event handling
  • Script execution (ServerScript/ClientScript)

Key Features:

  • Context loaders (dynamic data injection)
  • Event-driven architecture
  • Process instance state management
  • Activity tracking

Dependencies:

  • All domain modules (executes workflows for all)
  • Notification Service (user task notifications)

Implementation: BankLingo.Entities.ExecutionEngine

Transaction Managementโ€‹

Purpose: Universal transaction lifecycle management

Responsibilities:

  • Transaction state management (PENDING/SETTLED/CANCELLED/REVERSED)
  • Approval workflow coordination
  • Transaction impact tracking
  • Reversal processing

Key Components:

  • ApproveTransactionCommand
  • RejectTransactionCommand
  • CancelTransactionCommand
  • ReverseTransactionCommand
  • TransactionImpactRecord system

Dependencies:

  • All transaction modules (Deposits, Loans, Teller, Vault, Cheque)
  • Audit Service (transaction trail)

Implementation: CB.Administration.Api/Commands/BPMCore/TransactionManagement

Notification Serviceโ€‹

Purpose: Multi-channel notification delivery

Responsibilities:

  • Email notifications
  • SMS notifications
  • Push notifications
  • In-app notifications
  • Notification templating

Dependencies:

  • Azure Service Bus (message queue)
  • External SMS gateway
  • Email service provider

Channels:

  • Email (SendGrid/SMTP)
  • SMS (Twilio/local gateway)
  • Push (Firebase Cloud Messaging)

Audit Serviceโ€‹

Purpose: Compliance and audit trail management

Responsibilities:

  • Activity logging
  • Transaction auditing
  • Change tracking
  • Compliance reporting
  • Audit trail storage

Dependencies:

  • Azure Blob Storage (log archival)
  • SQL Database (audit records)

Logged Events:

  • All transactions
  • State changes
  • User activities
  • System events

Component Interaction Patternsโ€‹

1. Transaction Processing Flowโ€‹

2. Approval Workflowโ€‹

3. Process Engine Integrationโ€‹

Dependency Graphโ€‹

Module Communication Patternsโ€‹

1. Command Pattern (MediatR)โ€‹

All modules use MediatR for command handling:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Benefits:

  • Decoupling of modules
  • Single responsibility
  • Easy testing
  • Pipeline behaviors (logging, validation)

2. Event-Driven Patternโ€‹

Modules communicate through domain events:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Benefits:

  • Loose coupling
  • Asynchronous processing
  • Scalability
  • Audit trail

3. Repository Patternโ€‹

Data access abstraction:

Code Removed

Implementation details removed for security.

Contact support for implementation guidance.

Benefits:

  • Abstraction of data access
  • Testability
  • Centralized data logic
  • Query optimization

API Boundariesโ€‹

BPM Command APIโ€‹

Endpoint: POST /api/bpm/cmd

Purpose: Unified command execution endpoint

Request Format:

{
  "commandName": "InitiateDepositCommand",
  "data": {
    "accountEncodedKey": "...",
    "amount": 1000.00,
    "requireApproval": false
  }
}

Response Format:

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Transaction completed successfully",
  "data": {
    "transactionKey": "DEP123456",
    "balance": 11000.00
  }
}

Supported Commands:

  • Deposit transactions
  • Withdrawal transactions
  • Loan transactions
  • Teller transactions
  • Vault transactions
  • Cheque transactions
  • Universal transaction management

Query APIโ€‹

Endpoint: POST /api/bpm/query

Purpose: Data retrieval and reporting

Request Format:

{
  "queryName": "RetrieveDepositAccountQuery",
  "data": {
    "accountNumber": "1234567890"
  }
}

Process APIโ€‹

Endpoint: POST /api/bpm/process

Purpose: BPMN process management

Operations:

  • Start process instance
  • Complete user task
  • Query process state
  • Cancel process
  • Pause/Resume process

Component Scalabilityโ€‹

Horizontal Scalingโ€‹

Stateless Components (can scale horizontally):

  • API Gateway
  • All domain modules
  • Query services
  • Command handlers

Stateful Components (require coordination):

  • Process Engine (sticky sessions)
  • Transaction Management (distributed locks)

Vertical Scalingโ€‹

Resource-Intensive Components:

  • Calculation Services (interest, amortization)
  • Reporting Services (large datasets)
  • Batch Processing (end-of-day)

Technology Stack by Componentโ€‹

ComponentTechnologyVersion
API GatewayASP.NET Core Web API.NET 8
Domain ModulesC# Class Libraries.NET 8
Process EngineCustom BPMN Engine.NET 8
Command HandlingMediatR12.x
Data AccessEntity Framework Core8.x
CachingRedis7.x
ValidationFluentValidation11.x
MappingAutoMapper12.x
LoggingSerilog3.x
TestingxUnit, MoqLatest

Component Isolationโ€‹

Bounded Contextsโ€‹

Each module represents a bounded context in DDD:

  1. Deposits Context: Deposit accounts, transactions, products
  2. Loans Context: Loan accounts, schedules, repayments
  3. Tellering Context: Tills, teller operations, cash
  4. Vault Context: Branch vaults, cash positions
  5. Cheque Context: Cheque books, clearing, bouncing

Context Integrationโ€‹

Shared Kernel:

  • Transaction Management (universal)
  • Audit/Logging (universal)
  • Authentication (universal)

Published Language:

  • Commands (for operations)
  • Queries (for data retrieval)
  • Events (for notifications)

Component Deploymentโ€‹

Deployment Unitsโ€‹

  1. Core API (single deployment):

    • All domain modules
    • Process Engine
    • Transaction Management
    • Shared services

  2. Background Services (separate deployments):

    • Notification Service
    • Batch Processing Service
    • Report Generation Service

Advantages of Monolithic Deploymentโ€‹

  • Simplified deployment
  • Shared transaction boundaries
  • Easier debugging
  • Lower operational overhead

Microservices Migration Pathโ€‹

Future potential microservices:

  1. Notification Service รขโ€ โ€™ Independent service
  2. Reporting Service รขโ€ โ€™ Independent service
  3. Batch Processing รขโ€ โ€™ Independent service

Summaryโ€‹

The component architecture demonstrates:

  • รขล“โ€ฆ Clear separation of concerns - Modules with single responsibilities
  • รขล“โ€ฆ Loose coupling - Modules communicate through abstractions
  • รขล“โ€ฆ High cohesion - Related functionality grouped together
  • รขล“โ€ฆ Scalability - Stateless components can scale horizontally
  • รขล“โ€ฆ Testability - Components can be tested in isolation
  • รขล“โ€ฆ Maintainability - Changes localized to specific modules

Key Design Principles:

  1. Domain-Driven Design (DDD)
  2. SOLID principles
  3. Command Query Responsibility Segregation (CQRS)
  4. Event-Driven Architecture
  5. Repository Pattern
  6. Dependency Injection