System Modules
The Bank Teller Solution is composed of nine focused modules. Each module owns a specific slice of the business domain — they communicate through the API and share infrastructure (PostgreSQL, Keycloak, OPA) but are otherwise independent.
Transaction Processing
LiveCore teller operations
Handles all money-movement operations a teller performs at the counter. Each transaction is validated by OPA, posted through the ESB, and recorded against the active drawer session.
Key capabilities
- Cash deposit and withdrawal
- Cheque deposit
- Transaction reversal
- Foreign currency exchange (over-counter and internal)
- Own-account and third-party IBAN transfers
- Utility bill payment
- OPA cash-limit enforcement per entity and currency
Who uses it
Drawer Management
LiveTeller cash drawer lifecycle
Each teller has one drawer per business day. Opening requires a valid roster entry. The drawer tracks denomination-level balances throughout the session and enforces a zero-carryover rule at close.
Key capabilities
- Open drawer with initial denomination counts
- Real-time balance tracking by currency and denomination
- Cash transfer to and from the vault (dual-control)
- Teller-to-teller cash exchange
- Close drawer — rejected if any currency balance ≠ 0
- Supervisor view of all open drawers in the branch
Who uses it
Vault Management
LiveBranch vault with dual-control
The branch vault holds denomination-tracked cash reserves. Every vault operation requires two authorized officers from complementary role levels — one initiates, the other approves.
Key capabilities
- Open and close with denomination counts
- Cash transfer in and out of the vault
- Dual-control: Supervisor initiates → BranchManager approves (and vice versa)
- Step-up re-authentication required at approval time
- Full denomination-level balance tracking
Who uses it
Branch Operations
LiveDaily branch lifecycle
Controls the branch's operating state for the business day. A branch must be Open and a business session active before tellers can process transactions. The branch lifecycle panel gives a visual overview of every step.
Key capabilities
- Branch open and close (BranchManager only)
- Emergency force-close with mandatory audit reason
- Business session open and close
- Business day registration and management
- Visual lifecycle panel: Branch → Session → Vault → Drawers
Who uses it
Dual-Control Approvals
LiveMaker-checker engine
All vault and drawer–vault operations create a pending approval before executing. The approval engine enforces role-complement checks — the approver must come from a different authority tier than the initiator.
Key capabilities
- Pending approval queue per branch
- Approve or reject with full audit trail
- Role-complement enforcement (Supervisor ↔ BranchManager)
- Initiator role recorded at creation time
- Complete approval history (not just pending)
Who uses it
Identity & Access
LiveKeycloak PKCE authentication
All users authenticate through Keycloak using the PKCE authorization code flow. JWT claims carry the user's entity, branch assignment, and role into every API request. Sensitive operations trigger a step-up re-login.
Key capabilities
- PKCE authorization code flow — no client secret in the browser
- Keycloak realm: mithaq-bank
- Roles: Teller · HeadTeller · Supervisor · BranchManager
- Custom JWT claims: bank_entity, bank_branch_id
- Step-up re-auth for vault approvals (prompt=login, 15-min token freshness)
- Admin App can create, update, and delete Keycloak users
Who uses it
OPA Policy Engine
LiveAttribute-Based Access Control
Open Policy Agent runs as a sidecar and evaluates every transaction and vault action. Policies are data-driven — cash limits are stored in PostgreSQL and pushed to OPA on startup and on every save.
Key capabilities
- Per-currency cash limits scoped to each entity
- Supervisor override token for high-value transactions (5-min TTL)
- ABAC: role, entity, branch, and currency all factored in
- Live Rego policy editor in the Admin Portal
- Cash limits auto-sync from DB on startup and on every change
- Hard-deny when OPA is unreachable
Who uses it
Admin Portal
LiveBranch configuration and user management
Gives Branch Managers a single place to configure their branch: staff rosters, business days, cash limits, denomination sets, and — via Keycloak and OPA — user accounts and live security policy. All data is China-Wall scoped to the manager's own entity and branch.
Key capabilities
- Teller roster management by date
- Business day registration
- Cash limit configuration (auto-syncs to OPA on save)
- Denomination set management
- Keycloak user CRUD — create, edit, reset password, delete
- Live Rego policy editor and OPA data viewer
- China-Wall scoping — managers only see their own entity and branch
Who uses it
ESB Integration
PartialCore Banking System adapter
The Enterprise Service Bus decouples the teller platform from the Core Banking System. In development, a .NET 9 mock ESB simulates CBS responses so the full flow can be tested end-to-end without a real core.
Key capabilities
- CBS adapter layer for all money-movement operations
- .NET 9 mock ESB running on port 5100
- Account validation and balance inquiry
- Transaction posting and confirmation
- Pluggable design — swap the mock for a real CBS adapter without changing the teller API
Who uses it
How the modules connect
Prerequisites chain: The branch must be Open before a Business Session can start, which must be active before the Vault can open, which must be open before Drawers can be opened and Transactions processed.
Every request goes through: Keycloak (who are you?) → OPA (are you allowed?) → the teller API (do the business rules pass?) → ESB (post to the core).
Dual-control path: Any vault or drawer–vault operation creates a pending approval instead of executing immediately. A second officer from the correct role tier must approve it — and for vault operations must re-authenticate first.
Admin changes take effect live: Cash limit updates in the Admin Portal sync to OPA immediately, affecting the next transaction without a restart.