Initial commit

2025-12-12 15:02:56 -08:00
commit 849e6a8357
891 changed files with 167728 additions and 0 deletions
--- a/docs/flows/README.md
+++ b/docs/flows/README.md
@@ -0,0 +1,181 @@
+# DBIS Flow Process Documentation
+
+This directory contains detailed flow documentation for all major DBIS processes. Each flow document includes visual diagrams, step-by-step processes, error handling, integration points, code references, and performance metrics.
+
+## Flow Documentation Index
+
+### Payment & Settlement Flows
+
+1. **[GPN Payment Flow](./gpn-payment-flow.md)** - GPN payment routing and settlement flow
+   - Three-layer payment processing (Sovereign Access, Global Switching, Finality)
+   - ISO 20022 message handling
+   - Hash-lock verification
+
+2. **[M-RTGS Settlement Flow](./m-rtgs-settlement-flow.md)** - M-RTGS multi-asset settlement flow
+   - Multi-asset real-time gross settlement
+   - Priority queue management
+   - < 100ms settlement target
+
+3. **[GSS Settlement Flow](./gss-settlement-flow.md)** - GSS four-layer settlement flow
+   - Dual-ledger synchronization (SCB + DBIS)
+   - Four-layer architecture
+   - Sovereign signature validation
+
+4. **[Atomic Settlement Flow](./atomic-settlement-flow.md)** - Atomic settlement dual-commitment flow
+   - Dual-commitment protocol
+   - Cross-chain verification
+   - Settlement finality
+
+5. **[Cross-Chain Settlement Flow](./cross-chain-settlement-flow.md)** - Cross-chain settlement flow
+   - Multi-ledger atomic swaps
+   - Commitment creation and verification
+   - Cross-chain contract execution
+
+### CBDC Flows
+
+6. **[CBDC Mint Burn Flow](./cbdc-mint-burn-flow.md)** - CBDC minting and burning flow
+   - 1:1 reserve backing verification
+   - Ledger posting
+   - Treasury account management
+
+7. **[CBDC Wallet Transfer Flow](./cbdc-wallet-transfer-flow.md)** - CBDC wallet transfer flow
+   - Cross-wallet transfers
+   - Compliance checks
+   - Balance verification
+
+8. **[CBDC Interoperability Flow](./cbdc-interoperability-flow.md)** - Cross-sovereign CBDC interoperability flow
+   - CIM identity mapping
+   - Interledger conversion
+   - Cross-sovereign transfers
+
+9. **[Offline Capsule Flow](./offline-capsule-flow.md)** - Offline CBDC capsule flow
+   - Capsule creation
+   - Offline transfer
+   - Capsule redemption
+
+### FX & SSU Flows
+
+10. **[FX Trade Execution Flow](./fx-trade-execution-flow.md)** - FX order submission and execution flow
+    - Market/limit order processing
+    - Price calculation (VWAP/TWAP)
+    - Trade execution
+
+11. **[SSU Mint Burn Flow](./ssu-mint-burn-flow.md)** - SSU minting and burning flow
+    - Composition calculation
+    - Liquidity verification
+    - Transaction creation
+
+12. **[SSU Atomic Settlement Flow](./ssu-atomic-settlement-flow.md)** - SSU-based atomic settlement flow
+    - SSU balance verification
+    - Atomic swap execution
+    - Settlement confirmation
+
+13. **[FX/SSU Integration Flow](./fx-ssu-integration-flow.md)** - FX/SSU/GRU integration flow
+    - Optimal routing calculation
+    - SSU adjustment
+    - GRU reserve layer integration
+
+### Identity & Compliance Flows
+
+14. **[Identity Verification Flow](./identity-verification-flow.md)** - GBIG/ILIE identity verification flow
+    - Identity lookup
+    - Trust scoring
+    - Cross-layer identity verification
+
+15. **[AML Screening Flow](./aml-screening-flow.md)** - AML/CTF screening and compliance flow
+    - Sanctions checking
+    - PEP detection
+    - Pattern analysis
+    - Risk scoring
+
+16. **[KYC Enforcement Flow](./kyc-enforcement-flow.md)** - KYC standards enforcement flow
+    - Cross-sovereign KYC verification
+    - Minimum standards checking
+    - Certification level validation
+
+17. **[RegTech Monitoring Flow](./regtech-monitoring-flow.md)** - RegTech supervision and monitoring flow
+    - Real-time behavior monitoring
+    - Pattern detection
+    - Alert generation
+
+### Liquidity & Treasury Flows
+
+18. **[GLP Contribution Withdrawal Flow](./glp-contribution-withdrawal-flow.md)** - GLP liquidity contribution/withdrawal flow
+    - Three-tier withdrawal system
+    - Multi-source aggregation
+    - Crisis intervention
+
+19. **[ID-SLG Liquidity Flow](./id-slg-liquidity-flow.md)** - ID-SLG infinite liquidity grid flow
+    - Liquidity projection
+    - Auto-generation within limits
+    - Continuum operations
+
+20. **[TRLM Mesh Flow](./trlm-mesh-flow.md)** - TRLM trans-reality liquidity mesh flow
+    - Cross-reality liquidity routing
+    - Mesh allocation
+    - Reality synchronization
+
+### Quantum & Advanced Flows
+
+21. **[GQL Quantum Ledger Flow](./gql-quantum-ledger-flow.md)** - GQL quantum ledger operations flow
+    - Quantum-resistant transaction posting
+    - XMSS/SPHINCS+ signature verification
+    - Q-Keccak hashing
+
+22. **[Omega Layer Settlement Flow](./omega-layer-settlement-flow.md)** - Ω-LSF settlement fabric flow
+    - Omega-layer MERGE operations
+    - Reality-spanning settlement
+    - Coherence verification
+
+23. **[Temporal Settlement Flow](./temporal-settlement-flow.md)** - CSSE temporal settlement flow
+    - Pre-commit phase
+    - Commit phase
+    - Reconciliation phase
+
+24. **[Multiversal Settlement Flow](./multiversal-settlement-flow.md)** - OSSM multiversal settlement flow
+    - 4D matrix settlement
+    - Cross-reality synchronization
+    - State merging
+
+### Legacy Integration Flows
+
+25. **[QPS Legacy Bridge Flow](./qps-legacy-bridge-flow.md)** - QPS legacy system bridging flow
+    - Message translation
+    - Legacy format conversion
+    - DBIS routing
+
+26. **[ISO 20022 Message Flow](./iso20022-message-flow.md)** - ISO 20022 message processing flow
+    - Message parsing
+    - Validation
+    - DBIS conversion
+
+27. **[SWIFT Integration Flow](./swift-integration-flow.md)** - SWIFT/ACH integration flow
+    - SWIFT message handling
+    - ACH processing
+    - Legacy network integration
+
+---
+
+## Flow Documentation Format
+
+Each flow document follows this structure:
+
+1. **Overview** - Purpose and scope of the flow
+2. **Prerequisites** - Required system states and conditions
+3. **Visual Flow Diagram** - ASCII sequence diagram showing the process
+4. **Step-by-Step Process** - Detailed numbered steps with explanations
+5. **Error Handling** - Error scenarios, recovery procedures, and rollback logic
+6. **Integration Points** - Related systems, APIs, and service dependencies
+7. **Code References** - Links to relevant service files and implementations
+8. **Performance Metrics** - Expected timing, throughput, and resource usage
+9. **Security Considerations** - Security checkpoints, authentication, and authorization
+10. **Testing Scenarios** - Test cases for validation and edge cases
+
+---
+
+## Related Documentation
+
+- [Architecture Atlas](../architecture-atlas.md) - System overview
+- [Diagram Library](../diagrams/README.md) - Reusable diagram components
+- [Technical Deep-Dive](../architecture-atlas-technical.md) - Implementation details
+
--- a/docs/flows/aml-screening-flow.md
+++ b/docs/flows/aml-screening-flow.md
@@ -0,0 +1,295 @@
+# AML Screening Flow
+
+## Overview
+
+The AML/CTF screening system performs comprehensive transaction monitoring, sanctions checking, PEP (Politically Exposed Person) detection, and pattern analysis to identify potential money laundering or terrorist financing activities. This flow documents the complete screening and risk scoring process.
+
+## Prerequisites
+
+- Transaction exists with entity information
+- AML service operational
+- Sanctions lists available
+- PEP database accessible
+- RegTech supervision engine available
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ Transaction │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Sanctions Check
+       ▼
+┌─────────────────────────┐
+│ Check Sanctions List    │
+│  - Entity name lookup    │
+│  - OFAC, EU, UN lists    │
+│  - Risk: +100 if match   │
+└──────┬──────────────────┘
+       │
+       │ 2. PEP Check
+       ▼
+┌─────────────────────────┐
+│ Check PEP List          │
+│  - Entity name lookup    │
+│  - PEP database          │
+│  - Risk: +50 if match    │
+└──────┬──────────────────┘
+       │
+       │ 3. Pattern Detection
+       ▼
+┌─────────────────────────┐
+│ Detect Anomalous        │
+│  Patterns                │
+│  - Velocity analysis     │
+│  - Circular transfers    │
+│  - Risk score            │
+└──────┬──────────────────┘
+       │
+       │ 4. AML Behavior Monitoring
+       ▼
+┌─────────────────────────┐
+│ RegTech AML Behavior    │
+│  Monitoring              │
+│  - Rule evaluation       │
+│  - Critical behaviors    │
+│  - Risk: +50 per critical│
+└──────┬──────────────────┘
+       │
+       │ 5. Calculate Risk Score
+       ▼
+┌─────────────────────────┐
+│ Determine Status        │
+│  - CLEAR: < 50          │
+│  - FLAGGED: 50-99        │
+│  - BLOCKED: >= 100       │
+└──────┬──────────────────┘
+       │
+       │ 6. Create Record
+       ▼
+┌─────────────┐
+│ Compliance  │
+│  Record     │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Sanctions Screening
+1. Receive screening request with:
+   - Sovereign bank ID
+   - Transaction ID
+   - Entity name (optional)
+   - Entity type (optional)
+2. Initialize risk score: `0`
+3. Initialize screening results object
+4. If entity name provided:
+   - Check sanctions lists:
+     - OFAC (Office of Foreign Assets Control)
+     - EU sanctions list
+     - UN sanctions list
+   - Query sanctions database
+   - If match found:
+     - Set `sanctionsMatch: true` in results
+     - Add risk score: `+100` (critical match)
+5. Store sanctions check result
+
+**Code Reference**: `src/core/compliance/aml.service.ts:19-82`
+
+### Step 2: PEP Screening
+1. If entity name provided:
+   - Check PEP (Politically Exposed Person) database
+   - Query PEP list by entity name
+   - If match found:
+     - Set `pepMatch: true` in results
+     - Add risk score: `+50` (high risk)
+2. Store PEP check result
+
+**Code Reference**: `src/core/compliance/aml.service.ts:37-44`
+
+### Step 3: Pattern Detection
+1. Analyze transaction for anomalous patterns:
+   - Transaction velocity (frequency)
+   - Amount patterns
+   - Geographic patterns
+   - Time-based patterns
+2. Detect specific patterns:
+   - Circular transfers (money going in circles)
+   - Synthetic layering (complex transaction chains)
+   - Structuring (breaking large amounts into smaller)
+   - Rapid movement (velocity anomalies)
+3. Calculate pattern risk score:
+   - Each pattern adds to risk score
+   - Pattern severity determines weight
+4. Store pattern risk in results
+
+**Code Reference**: `src/core/compliance/aml.service.ts:46-49`
+
+### Step 4: AML Behavior Monitoring
+1. Call RegTech supervision engine:
+   - Pass transaction ID
+   - Pass sovereign bank ID
+   - Request AML behavior monitoring
+2. Supervision engine evaluates AML rules:
+   - Retrieves active AML behavior rules
+   - Evaluates each rule against transaction
+   - Returns triggered behaviors
+3. Process behavior results:
+   - Filter critical behaviors (severity: `critical`)
+   - For each critical behavior:
+     - Add risk score: `+50`
+   - Store all behaviors in results
+4. Store AML behavior results
+
+**Code Reference**: 
+- `src/core/compliance/aml.service.ts:51-57`
+- `src/core/compliance/regtech/supervision-engine.service.ts:22-50`
+
+### Step 5: Risk Score Calculation
+1. Sum all risk components:
+   - Sanctions match: `+100` (if match)
+   - PEP match: `+50` (if match)
+   - Pattern risk: variable
+   - Critical AML behaviors: `+50` each
+2. Total risk score = sum of all components
+
+### Step 6: Status Determination
+1. Determine compliance status based on risk score:
+   - **CLEAR**: Risk score < 50
+   - **FLAGGED**: Risk score >= 50 and < 100
+   - **BLOCKED**: Risk score >= 100
+2. Status thresholds:
+   - `AML_RISK_CRITICAL`: 100
+   - `AML_RISK_HIGH`: 50
+
+**Code Reference**: `src/core/compliance/aml.service.ts:59-65`
+
+### Step 7: Create Compliance Record
+1. Create compliance record in database:
+   - Sovereign bank ID
+   - Transaction ID
+   - Record type: `AML_CHECK`
+   - Entity name (if provided)
+   - Entity type (if provided)
+   - Risk score
+   - Status (CLEAR, FLAGGED, or BLOCKED)
+   - Screening result (all check results)
+   - Timestamp
+2. Return compliance record
+
+**Code Reference**: `src/core/compliance/aml.service.ts:67-82`
+
+## Error Handling
+
+### Error: Transaction Not Found
+- **Detection**: Transaction ID doesn't exist
+- **Action**: Continue screening with available data
+- **Recovery**: Verify transaction ID
+
+### Error: Sanctions Database Unavailable
+- **Detection**: Cannot query sanctions list
+- **Action**: Log warning, continue with other checks
+- **Recovery**: Retry sanctions check, use cached data
+
+### Error: RegTech Engine Unavailable
+- **Detection**: Supervision engine returns error
+- **Action**: Log warning, continue without AML behavior check
+- **Recovery**: Retry AML behavior monitoring
+
+### Error: Pattern Detection Failure
+- **Detection**: Pattern analysis throws error
+- **Action**: Set pattern risk to 0, continue
+- **Recovery**: Investigate pattern detection service
+
+## Integration Points
+
+### Related Services
+- **AML Service**: `src/core/compliance/aml.service.ts`
+- **Supervision Engine**: `src/core/compliance/regtech/supervision-engine.service.ts`
+- **Sanctions Database**: External sanctions lists (OFAC, EU, UN)
+- **PEP Database**: External PEP database
+
+### API Endpoints
+- `POST /api/v1/compliance/aml/screen` - Screen transaction
+- `GET /api/v1/compliance/aml/:recordId` - Get screening record
+- `GET /api/v1/compliance/aml/transactions/:transactionId` - Get transaction screening
+
+### Database Models
+- `ComplianceRecord` - Compliance screening records
+- `SanctionsList` - Sanctions list entries
+- `SupervisionRule` - AML behavior rules
+
+## Performance Metrics
+
+- **Sanctions Check**: < 50ms target
+- **PEP Check**: < 50ms target
+- **Pattern Detection**: < 100ms target
+- **AML Behavior Monitoring**: < 200ms target
+- **Total End-to-End**: < 400ms target
+- **Throughput**: 10,000+ screenings/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Data Privacy
+- Entity information handled securely
+- Screening results encrypted
+- Access restricted to authorized personnel
+
+### Real-Time Screening
+- Screening performed before transaction execution
+- Blocked transactions prevented from processing
+- Flagged transactions require review
+
+### Audit Trail
+- All screening results logged
+- Risk scores recorded
+- Status changes tracked
+
+## Testing Scenarios
+
+### Happy Path - CLEAR
+1. Valid transaction
+2. No sanctions match
+3. No PEP match
+4. No anomalous patterns
+5. No critical AML behaviors
+6. Risk score < 50
+7. Status: CLEAR
+
+### Happy Path - FLAGGED
+1. Valid transaction
+2. PEP match found
+3. Risk score >= 50 and < 100
+4. Status: FLAGGED
+5. Requires review
+
+### Happy Path - BLOCKED
+1. Valid transaction
+2. Sanctions match found
+3. Risk score >= 100
+4. Status: BLOCKED
+5. Transaction prevented
+
+### Error Scenarios
+1. Transaction not found
+2. Sanctions database unavailable
+3. RegTech engine unavailable
+4. Pattern detection failure
+
+### Edge Cases
+1. Multiple sanctions matches
+2. Both PEP and sanctions match
+3. Multiple critical AML behaviors
+4. High pattern risk score
+5. Concurrent screenings for same transaction
+
+---
+
+**Related Flows**:
+- [Identity Verification Flow](./identity-verification-flow.md)
+- [KYC Enforcement Flow](./kyc-enforcement-flow.md)
+- [RegTech Monitoring Flow](./regtech-monitoring-flow.md)
+
--- a/docs/flows/atomic-settlement-flow.md
+++ b/docs/flows/atomic-settlement-flow.md
@@ -0,0 +1,273 @@
+# Atomic Settlement Flow
+
+## Overview
+
+Atomic settlement ensures that cross-chain and cross-ledger transactions either complete entirely or fail entirely, with no partial state. This flow implements a dual-commitment protocol that commits to both sovereign and DBIS master ledgers atomically.
+
+## Prerequisites
+
+- Source and destination banks are registered
+- Valid transaction request
+- Sufficient balance in source account
+- Both ledgers (sovereign and DBIS) are operational
+- Atomic settlement service initialized
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ Transaction │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Prepare Commitment
+       ▼
+┌─────────────────────────┐
+│ Prepare Dual-Commitment │
+│  - Generate commitment   │
+│  - Create settlement ID  │
+└──────┬──────────────────┘
+       │
+       │ 2. Commit to Sovereign
+       ▼
+┌─────────────────────────┐
+│ Commit to Sovereign    │
+│  Ledger                  │
+│  - Post debit/credit    │
+│  - Generate hash         │
+└──────┬──────────────────┘
+       │
+       │ 3. Commit to DBIS
+       ▼
+┌─────────────────────────┐
+│ Commit to DBIS Master   │
+│  Ledger                  │
+│  - Post debit/credit    │
+│  - Generate hash         │
+└──────┬──────────────────┘
+       │
+       │ 4. Verify Commitments
+       ▼
+┌─────────────────────────┐
+│ Verify Dual-Commitment  │
+│  - Compare hashes        │
+│  - Verify both posted    │
+└──────┬──────────────────┘
+       │
+       │ 5. Finalize
+       ▼
+┌─────────────┐
+│ Settlement  │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Prepare Dual-Commitment
+1. Receive atomic settlement request with:
+   - Source bank ID
+   - Destination bank ID
+   - Amount and currency
+   - Asset type
+   - Transaction ID (optional)
+2. Generate unique settlement ID: `{uuid}`
+3. Generate transaction ID if not provided: `{uuid}`
+4. Create commitment data structure:
+   - Settlement ID
+   - Transaction details
+   - Timestamp
+   - Nonce for uniqueness
+5. Prepare commitment hash input
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts:33-42`
+
+### Step 2: Commit to Sovereign Ledger
+1. Post to sovereign ledger:
+   - Lookup source account in sovereign bank
+   - Lookup destination account
+   - Create debit entry on source
+   - Create credit entry on destination
+   - Use ledger ID: `Sovereign_{sourceBankId}`
+2. Retrieve ledger entry
+3. Extract block hash from ledger entry
+4. Store sovereign ledger hash
+5. If posting fails, throw error and terminate
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts:44-49`
+
+### Step 3: Commit to DBIS Master Ledger
+1. Post to DBIS master ledger:
+   - Lookup source account
+   - Lookup destination account
+   - Create debit entry on source
+   - Create credit entry on destination
+   - Use ledger ID: `Master`
+   - Include metadata: `{ atomicSettlement: true, settlementId }`
+2. Retrieve ledger entry
+3. Extract block hash from ledger entry
+4. Store DBIS ledger hash
+5. If posting fails, rollback sovereign ledger and throw error
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts:51-52`
+
+### Step 4: Verify Dual-Commitment
+1. Compare hashes:
+   - Retrieve sovereign ledger hash
+   - Retrieve DBIS ledger hash
+   - Verify both hashes exist and are non-empty
+2. Verify ledger entries:
+   - Query sovereign ledger entry by hash
+   - Query DBIS ledger entry by hash
+   - Verify both entries exist
+   - Verify entry details match (amount, accounts, etc.)
+3. If verification fails:
+   - Rollback both ledger entries
+   - Mark settlement as failed
+   - Throw error
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts:54-58`
+
+### Step 5: Finalize Settlement
+1. Calculate settlement time:
+   - Start time recorded at Step 1
+   - End time = current time
+   - Settlement time = end - start
+2. Create atomic settlement record:
+   - Settlement ID
+   - Transaction ID
+   - Source and destination bank IDs
+   - Amount, currency, asset type
+   - Settlement mode: `atomic`
+   - Dual-ledger commit: `true`
+   - Sovereign ledger hash
+   - DBIS ledger hash
+   - Settlement time (milliseconds)
+   - Status: `settled`
+   - Committed and settled timestamps
+3. Return settlement result with:
+   - Settlement ID
+   - Status: `settled`
+   - Both ledger hashes
+   - Settlement time
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts:60-90`
+
+### Step 6: Error Handling
+1. If any step fails:
+   - Create failed settlement record
+   - Set status: `failed`
+   - Set dual-ledger commit: `false`
+   - Record error details
+2. Rollback any partial ledger entries:
+   - If sovereign posted but DBIS failed: rollback sovereign
+   - If DBIS posted but verification failed: rollback both
+3. Log error for investigation
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts:91-111`
+
+## Error Handling
+
+### Error: Commitment Preparation Failure
+- **Detection**: Cannot generate commitment
+- **Action**: Return error, terminate flow
+- **Recovery**: Verify input parameters, retry
+
+### Error: Sovereign Ledger Post Failure
+- **Detection**: Ledger posting fails
+- **Action**: Terminate flow, no rollback needed
+- **Recovery**: Verify ledger availability, check account status
+
+### Error: DBIS Ledger Post Failure
+- **Detection**: DBIS posting fails after sovereign posted
+- **Action**: Rollback sovereign ledger entry
+- **Recovery**: Retry after verifying DBIS ledger status
+
+### Error: Dual-Commitment Verification Failure
+- **Detection**: Hashes don't match or entries missing
+- **Action**: Rollback both ledger entries
+- **Recovery**: 
+  - Investigate ledger integrity
+  - Verify hash generation
+  - Retry settlement
+
+### Error: Concurrent Modification
+- **Detection**: Account balance changed during settlement
+- **Action**: Rollback and retry
+- **Recovery**: Implement optimistic locking
+
+## Integration Points
+
+### Related Services
+- **Atomic Settlement Service**: `src/core/settlement/isn/atomic-settlement.service.ts`
+- **Ledger Service**: `src/core/ledger/ledger.service.ts`
+- **Account Service**: `src/core/accounts/account.service.ts`
+- **GSS Master Ledger**: `src/core/settlement/gss/gss-master-ledger.service.ts`
+
+### API Endpoints
+- `POST /api/v1/isn/atomic-settlement/execute` - Execute atomic settlement
+- `GET /api/v1/isn/atomic-settlement/:settlementId` - Get settlement status
+- `POST /api/v1/isn/atomic-settlement/verify` - Verify dual-commitment
+
+### Database Models
+- `AtomicSettlement` - Atomic settlement records
+- `LedgerEntry` - Individual ledger entries
+
+## Performance Metrics
+
+- **Commitment Preparation**: < 10ms target
+- **Sovereign Ledger Post**: < 50ms target
+- **DBIS Ledger Post**: < 50ms target
+- **Verification**: < 20ms target
+- **Total End-to-End**: < 130ms target
+- **Throughput**: 10,000+ atomic settlements/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Atomicity Guarantee
+- Dual-commitment ensures both ledgers update or neither
+- Rollback mechanism prevents partial state
+- Verification step ensures consistency
+
+### Data Integrity
+- Hash verification prevents tampering
+- Dual-ledger hashes provide proof
+- Settlement records provide audit trail
+
+### Concurrency Control
+- Account locking during settlement
+- Optimistic locking for balance checks
+- Transaction isolation
+
+## Testing Scenarios
+
+### Happy Path
+1. Valid settlement request
+2. Successful commitment preparation
+3. Successful sovereign ledger post
+4. Successful DBIS ledger post
+5. Verification passes
+6. Settlement finalized
+
+### Error Scenarios
+1. Commitment preparation failure
+2. Sovereign ledger post failure
+3. DBIS ledger post failure
+4. Verification failure
+5. Concurrent modification
+
+### Edge Cases
+1. Maximum settlement amount
+2. Minimum settlement amount
+3. Same bank source and destination
+4. Cross-currency settlement
+5. Network partition during settlement
+
+---
+
+**Related Flows**:
+- [GSS Settlement Flow](./gss-settlement-flow.md)
+- [Cross-Chain Settlement Flow](./cross-chain-settlement-flow.md)
+- [M-RTGS Settlement Flow](./m-rtgs-settlement-flow.md)
+
--- a/docs/flows/cbdc-interoperability-flow.md
+++ b/docs/flows/cbdc-interoperability-flow.md
@@ -0,0 +1,102 @@
+# CBDC Interoperability Flow
+
+## Overview
+
+CBDC interoperability enables cross-sovereign CBDC transfers through the CBDC Interoperability Matrix (CIM), including identity mapping, interledger conversion, and cross-certification.
+
+## Prerequisites
+
+- Source and destination CBDC systems are registered
+- CIM service operational
+- Identity mapping available
+- Interledger conversion supported
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ Cross-SCB   │
+│ CBDC Transfer│
+└──────┬──────┘
+       │
+       │ 1. Identity Mapping
+       ▼
+┌─────────────────────────┐
+│ Map Cross-Sovereign    │
+│  Identity               │
+│  - CIM lookup           │
+│  - Cross-certification  │
+└──────┬──────────────────┘
+       │
+       │ 2. Interledger Conversion
+       ▼
+┌─────────────────────────┐
+│ Convert Between Ledgers │
+│  - Source CBDC format    │
+│  - Target CBDC format    │
+│  - Rate calculation      │
+└──────┬──────────────────┘
+       │
+       │ 3. Execute Transfer
+       ▼
+┌─────────────────────────┐
+│ Execute Cross-SCB      │
+│  Transfer               │
+└──────┬──────────────────┘
+       │
+       │ 4. Complete
+       ▼
+┌─────────────┐
+│ Transfer    │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Identity Mapping
+1. Lookup source identity in CIM
+2. Map to destination sovereign identity
+3. Verify cross-certification
+4. Validate KYC/AML standards
+
+**Code Reference**: `src/core/cbdc/interoperability/cim-identity.service.ts`
+
+### Step 2: Interledger Conversion
+1. Determine conversion rate
+2. Convert amount to target CBDC
+3. Verify conversion parameters
+4. Create conversion record
+
+**Code Reference**: `src/core/cbdc/interoperability/cim-interledger.service.ts`
+
+### Step 3: Execute Transfer
+1. Post to source ledger (debit)
+2. Post to destination ledger (credit)
+3. Verify both postings
+4. Create interoperability record
+
+**Code Reference**: `src/core/cbdc/interoperability/cim-interledger.service.ts`
+
+## Error Handling
+
+- Identity mapping failure: Return error
+- Conversion failure: Rollback, return error
+- Transfer failure: Rollback both ledgers
+
+## Integration Points
+
+- CIM Identity Service: `src/core/cbdc/interoperability/cim-identity.service.ts`
+- CIM Interledger Service: `src/core/cbdc/interoperability/cim-interledger.service.ts`
+
+## Performance Metrics
+
+- Total End-to-End: < 200ms target
+- Throughput: 5,000+ conversions/second
+
+---
+
+**Related Flows**:
+- [CBDC Wallet Transfer Flow](./cbdc-wallet-transfer-flow.md)
+- [Identity Verification Flow](./identity-verification-flow.md)
+
--- a/docs/flows/cbdc-mint-burn-flow.md
+++ b/docs/flows/cbdc-mint-burn-flow.md
@@ -0,0 +1,310 @@
+# CBDC Mint Burn Flow
+
+## Overview
+
+CBDC minting and burning operations ensure 1:1 reserve backing for all CBDC issuance. This flow documents the complete process from reserve verification through ledger posting for both minting (issuance) and burning (redemption) operations.
+
+## Prerequisites
+
+- Sovereign bank is registered and active
+- Treasury account exists for the sovereign bank
+- Reserve account has sufficient balance (for minting)
+- Valid operator identity
+- CBDC service operational
+
+## Visual Flow Diagram
+
+### Minting Flow
+
+```
+┌─────────────┐
+│ Mint Request│
+└──────┬──────┘
+       │
+       │ 1. Verify Reserve
+       ▼
+┌─────────────────────────┐
+│ Verify 1:1 Reserve       │
+│  Backing                 │
+│  - Check reserve balance │
+│  - Verify >= mint amount │
+└──────┬──────────────────┘
+       │
+       │ 2. Reserve OK
+       ▼
+┌─────────────────────────┐
+│ Create Issuance Record  │
+│  - Record ID            │
+│  - Amount minted         │
+│  - Operator identity     │
+│  - Reserve backing       │
+└──────┬──────────────────┘
+       │
+       │ 3. Post to Ledger
+       ▼
+┌─────────────────────────┐
+│ Ledger Posting          │
+│  - Debit: Treasury       │
+│  - Credit: CBDC wallet   │
+│  - Type: TYPE_B          │
+└──────┬──────────────────┘
+       │
+       │ 4. Complete
+       ▼
+┌─────────────┐
+│ CBDC Minted │
+└─────────────┘
+```
+
+### Burning Flow
+
+```
+┌─────────────┐
+│ Burn Request│
+└──────┬──────┘
+       │
+       │ 1. Create Record
+       ▼
+┌─────────────────────────┐
+│ Create Issuance Record  │
+│  - Record ID            │
+│  - Amount burned        │
+│  - Operator identity     │
+└──────┬──────────────────┘
+       │
+       │ 2. Post to Ledger
+       ▼
+┌─────────────────────────┐
+│ Ledger Posting          │
+│  - Debit: CBDC wallet    │
+│  - Credit: Treasury      │
+│  - Type: TYPE_B          │
+└──────┬──────────────────┘
+       │
+       │ 3. Release Reserve
+       ▼
+┌─────────────┐
+│ CBDC Burned │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Minting Process
+
+#### Step 1: Reserve Verification
+1. Receive mint request with:
+   - Sovereign bank ID
+   - Wallet ID (optional)
+   - Amount to mint
+   - Operator identity
+   - Reason (optional)
+2. Get treasury account for sovereign bank:
+   - Lookup accounts by sovereign bank ID
+   - Filter by account type: `treasury`
+   - Filter by currency: `OMF` (reserve currency)
+3. Check reserve balance:
+   - Get current balance
+   - Compare with mint amount
+   - Verify: `reserveBalance >= mintAmount`
+4. If insufficient reserve, throw error: "Insufficient reserve backing for CBDC minting"
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:22-136`
+
+#### Step 2: Create Issuance Record
+1. Generate unique record ID: `CBDC-MINT-{uuid}`
+2. Create CBDC issuance record:
+   - Record ID
+   - Sovereign bank ID
+   - Wallet ID (if provided)
+   - Amount minted: `amount`
+   - Amount burned: `0`
+   - Net change: `amount`
+   - Operation type: `MINT`
+   - Operator identity
+   - Reserve backing: `amount` (1:1 backing)
+   - Timestamp: current UTC time
+   - Metadata: reason if provided
+3. Store record in database
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:38-52`
+
+#### Step 3: Ledger Posting
+1. Get treasury account (same as Step 1)
+2. Determine ledger ID: `{sovereignBankId}-CBDC`
+3. Post double-entry to ledger:
+   - Debit account: Treasury account ID
+   - Credit account: Treasury account ID (simplified - in production would be CBDC wallet)
+   - Amount: `amount`
+   - Currency: `OMDC` (CBDC currency code)
+   - Asset type: `CBDC`
+   - Entry type: `TYPE_B` (CBDC issuance)
+   - Reference ID: record ID
+   - Metadata: `{ operationType: 'mint', walletId, reason }`
+4. Verify ledger entry created successfully
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:54-67`
+
+#### Step 4: Return Result
+1. Map issuance record to CbdcIssuance type
+2. Return issuance details:
+   - Record ID
+   - Amount minted
+   - Reserve backing
+   - Timestamp
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:69`
+
+### Burning Process
+
+#### Step 1: Create Issuance Record
+1. Receive burn request with:
+   - Sovereign bank ID
+   - Wallet ID (optional)
+   - Amount to burn
+   - Operator identity
+   - Reason (optional)
+2. Generate unique record ID: `CBDC-BURN-{uuid}`
+3. Create CBDC issuance record:
+   - Record ID
+   - Sovereign bank ID
+   - Wallet ID (if provided)
+   - Amount minted: `0`
+   - Amount burned: `amount`
+   - Net change: `-amount` (negative)
+   - Operation type: `BURN`
+   - Operator identity
+   - Timestamp: current UTC time
+   - Metadata: reason if provided
+4. Store record in database
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:75-101`
+
+#### Step 2: Ledger Posting
+1. Get treasury account for sovereign bank
+2. Determine ledger ID: `{sovereignBankId}-CBDC`
+3. Post double-entry to ledger:
+   - Debit account: Treasury account ID (CBDC wallet - simplified)
+   - Credit account: Treasury account ID (Treasury - simplified)
+   - Amount: `amount`
+   - Currency: `OMDC`
+   - Asset type: `CBDC`
+   - Entry type: `TYPE_B` (CBDC redemption)
+   - Reference ID: record ID
+   - Metadata: `{ operationType: 'burn', walletId, reason }`
+4. Verify ledger entry created successfully
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:103-116`
+
+#### Step 3: Return Result
+1. Map issuance record to CbdcIssuance type
+2. Return issuance details:
+   - Record ID
+   - Amount burned
+   - Net change
+   - Timestamp
+
+**Code Reference**: `src/core/cbdc/cbdc.service.ts:118`
+
+## Error Handling
+
+### Error: Insufficient Reserve Backing
+- **Detection**: Reserve balance < mint amount
+- **Action**: Throw error "Insufficient reserve backing for CBDC minting"
+- **Recovery**: Add reserves, retry minting
+
+### Error: Treasury Account Not Found
+- **Detection**: No treasury account found
+- **Action**: Throw error "Treasury account not found"
+- **Recovery**: Create treasury account, retry
+
+### Error: Ledger Posting Failure
+- **Detection**: Ledger service returns error
+- **Action**: Rollback issuance record, throw error
+- **Recovery**: Verify ledger service, retry
+
+### Error: Invalid Amount
+- **Detection**: Amount <= 0
+- **Action**: Throw validation error
+- **Recovery**: Correct amount, retry
+
+## Integration Points
+
+### Related Services
+- **CBDC Service**: `src/core/cbdc/cbdc.service.ts`
+- **Account Service**: `src/core/accounts/account.service.ts`
+- **Ledger Service**: `src/core/ledger/ledger.service.ts`
+- **CBDC Wallet Service**: `src/core/cbdc/cbdc-wallet.service.ts`
+
+### API Endpoints
+- `POST /api/v1/cbdc/mint` - Mint CBDC
+- `POST /api/v1/cbdc/burn` - Burn CBDC
+- `GET /api/v1/cbdc/issuance/:recordId` - Get issuance record
+
+### Database Models
+- `CbdcIssuance` - CBDC issuance records
+- `CbdcWallet` - CBDC wallet records
+- `BankAccount` - Treasury accounts
+
+## Performance Metrics
+
+- **Reserve Verification**: < 20ms target
+- **Record Creation**: < 10ms target
+- **Ledger Posting**: < 50ms target
+- **Total End-to-End**: < 80ms target
+- **Throughput**: 5,000+ operations/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Reserve Backing
+- 1:1 reserve backing enforced
+- Reserve balance checked before minting
+- Reserve backing recorded in issuance record
+
+### Operator Identity
+- Operator identity required for all operations
+- Identity logged in issuance record
+- Audit trail for all mint/burn operations
+
+### Authorization
+- Only authorized operators can mint/burn
+- Sovereign bank must be active
+- Treasury account must exist
+
+## Testing Scenarios
+
+### Happy Path - Minting
+1. Valid mint request
+2. Sufficient reserve balance
+3. Successful record creation
+4. Successful ledger posting
+5. CBDC minted
+
+### Happy Path - Burning
+1. Valid burn request
+2. Successful record creation
+3. Successful ledger posting
+4. CBDC burned
+
+### Error Scenarios
+1. Insufficient reserve backing
+2. Treasury account not found
+3. Ledger posting failure
+4. Invalid amount
+5. Invalid operator identity
+
+### Edge Cases
+1. Maximum mint amount
+2. Minimum mint amount
+3. Mint with zero amount (should fail)
+4. Burn more than available
+5. Concurrent mint/burn operations
+
+---
+
+**Related Flows**:
+- [CBDC Wallet Transfer Flow](./cbdc-wallet-transfer-flow.md)
+- [CBDC Interoperability Flow](./cbdc-interoperability-flow.md)
+- [GSS Settlement Flow](./gss-settlement-flow.md)
+
--- a/docs/flows/cbdc-wallet-transfer-flow.md
+++ b/docs/flows/cbdc-wallet-transfer-flow.md
@@ -0,0 +1,106 @@
+# CBDC Wallet Transfer Flow
+
+## Overview
+
+CBDC wallet transfers enable movement of CBDC between wallets with compliance checks and balance verification. This flow documents the complete transfer process.
+
+## Prerequisites
+
+- Source and destination wallets exist and are active
+- Sufficient balance in source wallet
+- Compliance checks pass
+- CBDC transaction service operational
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ Transfer    │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Validate Wallets
+       ▼
+┌─────────────────────────┐
+│ Validate Wallets       │
+│  - Source wallet        │
+│  - Destination wallet   │
+│  - Balance check        │
+└──────┬──────────────────┘
+       │
+       │ 2. Compliance Check
+       ▼
+┌─────────────────────────┐
+│ Compliance Check        │
+│  - AML screening        │
+│  - KYC verification      │
+└──────┬──────────────────┘
+       │
+       │ 3. Execute Transfer
+       ▼
+┌─────────────────────────┐
+│ Execute Transfer        │
+│  - Update balances      │
+│  - Create transaction   │
+└──────┬──────────────────┘
+       │
+       │ 4. Complete
+       ▼
+┌─────────────┐
+│ Transfer    │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Validate Wallets
+1. Lookup source wallet
+2. Lookup destination wallet
+3. Verify both wallets are active
+4. Check source wallet balance
+5. Verify sufficient funds
+
+**Code Reference**: `src/core/cbdc/cbdc-wallet.service.ts`
+
+### Step 2: Compliance Check
+1. Run AML screening
+2. Verify KYC status
+3. Check transaction limits
+4. If compliance fails, reject transfer
+
+**Code Reference**: `src/core/compliance/aml.service.ts`
+
+### Step 3: Execute Transfer
+1. Create transaction record
+2. Update source wallet balance (debit)
+3. Update destination wallet balance (credit)
+4. Post to ledger
+5. Return transaction ID
+
+**Code Reference**: `src/core/cbdc/cbdc-transaction.service.ts`
+
+## Error Handling
+
+- Wallet not found: Return error
+- Insufficient balance: Return error
+- Compliance failure: Reject transfer
+- Ledger posting failure: Rollback balances
+
+## Integration Points
+
+- CBDC Wallet Service: `src/core/cbdc/cbdc-wallet.service.ts`
+- CBDC Transaction Service: `src/core/cbdc/cbdc-transaction.service.ts`
+- AML Service: `src/core/compliance/aml.service.ts`
+
+## Performance Metrics
+
+- Total End-to-End: < 150ms target
+- Throughput: 10,000+ transfers/second
+
+---
+
+**Related Flows**:
+- [CBDC Mint Burn Flow](./cbdc-mint-burn-flow.md)
+- [AML Screening Flow](./aml-screening-flow.md)
+
--- a/docs/flows/cross-chain-settlement-flow.md
+++ b/docs/flows/cross-chain-settlement-flow.md
@@ -0,0 +1,117 @@
+# Cross-Chain Settlement Flow
+
+## Overview
+
+Cross-chain settlement enables atomic swaps across multiple ledger types (sovereign, CBDC, commodity, security token chains). This flow documents the complete process from commitment creation through atomic swap execution.
+
+## Prerequisites
+
+- Source and destination chains are registered
+- Valid cross-chain settlement request
+- Sufficient balance/position in source chain
+- Cross-chain contract service operational
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ Settlement  │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Create Settlement Record
+       ▼
+┌─────────────────────────┐
+│ Create Settlement Record│
+│  - Settlement ID         │
+│  - Chain types & IDs     │
+│  - Amount & asset type   │
+└──────┬──────────────────┘
+       │
+       │ 2. Create Commitments
+       ▼
+┌─────────────────────────┐
+│ Create Cross-Chain      │
+│  Commitments             │
+│  - Source commitment     │
+│  - Target commitment     │
+└──────┬──────────────────┘
+       │
+       │ 3. Execute Atomic Swap
+       ▼
+┌─────────────────────────┐
+│ Execute Atomic Swap     │
+│  - Verify commitments    │
+│  - Execute on both chains│
+│  - Verify success        │
+└──────┬──────────────────┘
+       │
+       │ 4. Update Status
+       ▼
+┌─────────────┐
+│ Settlement  │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Create Settlement Record
+1. Receive cross-chain settlement request
+2. Generate settlement ID: `CCS-{uuid}`
+3. Create settlement record with source/target chain details
+4. Set status: `pending`
+
+**Code Reference**: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts:29-48`
+
+### Step 2: Create Commitments
+1. Create commitments for both chains
+2. Store commitment hashes
+3. Link to settlement record
+
+**Code Reference**: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts:85-124`
+
+### Step 3: Execute Atomic Swap
+1. Call cross-chain contract service
+2. Verify both commitments
+3. Execute swap on both chains atomically
+4. Verify execution success
+
+**Code Reference**: `src/core/settlement/cross-chain/cross-chain-contract.service.ts`
+
+### Step 4: Update Status
+1. If successful: Set status `settled`
+2. If failed: Set status `failed`
+3. Record completion timestamp
+
+**Code Reference**: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts:60-79`
+
+## Error Handling
+
+- Commitment creation failure: Rollback, return error
+- Atomic swap failure: Rollback both chains, mark failed
+- Verification failure: Mark failed, create reconciliation record
+
+## Integration Points
+
+- Cross-Chain Settlement Service: `src/core/settlement/cross-chain/cross-chain-settlement.service.ts`
+- Cross-Chain Contract Service: `src/core/settlement/cross-chain/cross-chain-contract.service.ts`
+- Atomic Settlement Service: `src/core/settlement/isn/atomic-settlement.service.ts`
+
+## Performance Metrics
+
+- Total End-to-End: < 200ms target
+- Throughput: 5,000+ settlements/second
+
+## Security Considerations
+
+- Atomic execution ensures both chains update or neither
+- Commitment verification prevents tampering
+- Hash verification ensures integrity
+
+---
+
+**Related Flows**:
+- [Atomic Settlement Flow](./atomic-settlement-flow.md)
+- [GSS Settlement Flow](./gss-settlement-flow.md)
+
--- a/docs/flows/fx-ssu-integration-flow.md
+++ b/docs/flows/fx-ssu-integration-flow.md
@@ -0,0 +1,36 @@
+# Fx Ssu Integration Flow
+
+## Overview
+
+This flow documents the fx ssu integration flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/fx-trade-execution-flow.md
+++ b/docs/flows/fx-trade-execution-flow.md
@@ -0,0 +1,266 @@
+# FX Trade Execution Flow
+
+## Overview
+
+The FX Engine processes foreign exchange orders through market or limit order types, calculates prices using VWAP/TWAP methods, and executes trades with proper settlement routing. This flow documents the complete order submission and execution process.
+
+## Prerequisites
+
+- Sovereign bank is registered and active
+- FX pair exists or can be created
+- Valid FX order (market or limit)
+- FX service operational
+- Market data available (for market orders)
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ FX Order    │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Get/Create Pair
+       ▼
+┌─────────────────────────┐
+│ Get or Create FX Pair   │
+│  - Lookup by pair code   │
+│  - Create if not exists  │
+└──────┬──────────────────┘
+       │
+       │ 2. Calculate Price
+       ▼
+┌─────────────────────────┐
+│ Calculate Price         │
+│  - Market: getMarketPrice│
+│  - Limit: use limitPrice │
+└──────┬──────────────────┘
+       │
+       │ 3. Create Trade
+       ▼
+┌─────────────────────────┐
+│ Create FX Trade Record  │
+│  - Trade ID             │
+│  - Pair, amount, price   │
+│  - Order type           │
+│  - Status: pending      │
+└──────┬──────────────────┘
+       │
+       │ 4. Execute Trade
+       ▼
+┌─────────────────────────┐
+│ Execute Trade           │
+│  - Update status        │
+│  - Set executed time    │
+└──────┬──────────────────┘
+       │
+       │ 5. Complete
+       ▼
+┌─────────────┐
+│ Trade       │
+│  Executed   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Get or Create FX Pair
+1. Receive FX order with:
+   - Sovereign bank ID
+   - FX pair code (e.g., "OMF/USD")
+   - Order type (MARKET or LIMIT)
+   - Amount
+   - Limit price (if LIMIT order)
+   - Settlement mode
+2. Parse pair code to extract base and quote currencies
+3. Lookup FX pair by pair code
+4. If pair doesn't exist:
+   - Create new FX pair record
+   - Set base currency
+   - Set quote currency
+   - Set pair code
+   - Set pricing method: `VWAP` (default)
+   - Set status: `active`
+5. Return FX pair (existing or newly created)
+
+**Code Reference**: `src/core/fx/fx.service.ts:22-147`
+
+### Step 2: Calculate Price
+1. Determine price based on order type:
+   - **MARKET order**: Get current market price
+     - Call `getMarketPrice(pair)`
+     - In production: fetch from market data feeds
+     - Currently: returns mock price based on pair
+   - **LIMIT order**: Use provided limit price
+     - Verify limit price is provided
+     - Use limit price directly
+2. If MARKET order and price unavailable:
+   - Throw error "Market price not available"
+3. If LIMIT order and limit price missing:
+   - Throw error "Invalid order type or missing limit price"
+
+**Code Reference**: `src/core/fx/fx.service.ts:29-37`
+
+### Step 3: Create FX Trade Record
+1. Generate unique trade ID: `FX-{uuid}`
+2. Create FX trade record:
+   - Trade ID
+   - Sovereign bank ID
+   - FX pair ID
+   - Base currency (from pair)
+   - Quote currency (from pair)
+   - Trade type: `SPOT` (default)
+   - Quantity: order amount
+   - Price: calculated price
+   - Order type: MARKET or LIMIT
+   - Initiator entity: sovereign bank ID
+   - Settlement mode: from order
+   - Status: `pending`
+   - Timestamp: current time
+3. Store trade in database
+4. Return trade ID and status
+
+**Code Reference**: `src/core/fx/fx.service.ts:39-62`
+
+### Step 4: Execute Trade
+1. Lookup trade by trade ID
+2. Verify trade exists and is in `pending` status
+3. Update trade record:
+   - Status: `executed`
+   - Executed at: current timestamp
+4. Map trade to FxTrade type
+5. Return executed trade details
+
+**Code Reference**: `src/core/fx/fx.service.ts:67-87`
+
+### Step 5: Market Price Calculation (for MARKET orders)
+1. Parse pair to extract base and quote currencies
+2. Get market price:
+   - In production: fetch from market data feeds
+   - Use VWAP (Volume Weighted Average Price) or TWAP (Time Weighted Average Price)
+   - Currently: return mock prices for known pairs
+3. Return price as string
+
+**Code Reference**: `src/core/fx/fx.service.ts:92-105`
+
+### Step 6: VWAP/TWAP Calculation (optional)
+1. **VWAP Calculation**:
+   - Get trade history for pair within time window (default 3600s)
+   - Calculate: `VWAP = Σ(price × volume) / Σ(volume)`
+   - Return VWAP price
+2. **TWAP Calculation**:
+   - Get price history for pair within time window
+   - Calculate: `TWAP = Σ(price × time_weight) / Σ(time_weight)`
+   - Return TWAP price
+
+**Code Reference**: `src/core/fx/fx.service.ts:110-123`
+
+## Error Handling
+
+### Error: Invalid Order Type
+- **Detection**: Order type not MARKET or LIMIT
+- **Action**: Throw validation error
+- **Recovery**: Correct order type, retry
+
+### Error: Missing Limit Price
+- **Detection**: LIMIT order without limit price
+- **Action**: Throw error "Invalid order type or missing limit price"
+- **Recovery**: Provide limit price, retry
+
+### Error: Market Price Unavailable
+- **Detection**: MARKET order but price unavailable
+- **Action**: Throw error "Market price not available"
+- **Recovery**: Wait for market data, retry, or use limit order
+
+### Error: Trade Not Found
+- **Detection**: Trade ID doesn't exist
+- **Action**: Throw error "FX trade not found"
+- **Recovery**: Verify trade ID, retry
+
+### Error: Trade Already Executed
+- **Detection**: Trade status is not `pending`
+- **Action**: Return existing trade (idempotent)
+- **Recovery**: Use existing trade result
+
+## Integration Points
+
+### Related Services
+- **FX Service**: `src/core/fx/fx.service.ts`
+- **Market Data Service**: (in production - external feeds)
+- **Settlement Service**: For trade settlement routing
+- **SIRE Routing**: For optimal settlement path
+
+### API Endpoints
+- `POST /api/v1/fx/orders` - Submit FX order
+- `POST /api/v1/fx/trades/:tradeId/execute` - Execute trade
+- `GET /api/v1/fx/trades/:tradeId` - Get trade details
+- `GET /api/v1/fx/pairs/:pairCode/price` - Get market price
+
+### Database Models
+- `FxTrade` - FX trade records
+- `FxPair` - FX pair definitions
+
+## Performance Metrics
+
+- **Pair Lookup/Creation**: < 10ms target
+- **Price Calculation**: < 20ms target (market data dependent)
+- **Trade Creation**: < 10ms target
+- **Trade Execution**: < 10ms target
+- **Total End-to-End**: < 50ms target
+- **Throughput**: 20,000+ orders/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Order Validation
+- Verify sovereign bank is active
+- Validate order parameters
+- Check amount limits
+
+### Price Verification
+- Market prices from trusted sources
+- Limit prices validated against market
+- Price manipulation detection
+
+### Trade Execution
+- Idempotent execution (can retry safely)
+- Trade status tracking
+- Audit trail for all trades
+
+## Testing Scenarios
+
+### Happy Path - Market Order
+1. Valid market order request
+2. FX pair exists or created
+3. Market price available
+4. Trade created successfully
+5. Trade executed successfully
+
+### Happy Path - Limit Order
+1. Valid limit order request
+2. FX pair exists or created
+3. Limit price provided
+4. Trade created successfully
+5. Trade executed successfully
+
+### Error Scenarios
+1. Invalid order type
+2. Missing limit price
+3. Market price unavailable
+4. Trade not found
+5. Trade already executed
+
+### Edge Cases
+1. Maximum order amount
+2. Minimum order amount
+3. New FX pair creation
+4. Concurrent orders for same pair
+5. Price calculation during high volatility
+
+---
+
+**Related Flows**:
+- [SSU Mint Burn Flow](./ssu-mint-burn-flow.md)
+- [FX/SSU Integration Flow](./fx-ssu-integration-flow.md)
+- [GSS Settlement Flow](./gss-settlement-flow.md)
+
--- a/docs/flows/glp-contribution-withdrawal-flow.md
+++ b/docs/flows/glp-contribution-withdrawal-flow.md
@@ -0,0 +1,36 @@
+# Glp Contribution Withdrawal Flow
+
+## Overview
+
+This flow documents the glp contribution withdrawal flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/gpn-payment-flow.md
+++ b/docs/flows/gpn-payment-flow.md
@@ -0,0 +1,392 @@
+# GPN Payment Flow
+
+## Overview
+
+The DBIS Global Payments Network (GPN) processes payments through a three-layer architecture: Sovereign Access Layer, Global Switching Layer, and Finality Layer. This flow documents the complete payment routing and settlement process.
+
+## Prerequisites
+
+- Source and destination accounts exist and are active
+- Sufficient balance in source account
+- Valid SDIP (Sovereign Digital Identity Passport) for authentication
+- GPN service is operational
+- ISO 20022 message format compliance
+
+## Visual Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant PI as Payment Initiator
+    participant L1 as Layer 1: Sovereign Access
+    participant L2 as Layer 2: Global Switching
+    participant L3 as Layer 3: Finality
+    participant SCB as SCB Ledger
+    participant DBIS as DBIS Ledger
+    
+    PI->>L1: Payment Request (PACS.008)
+    Note over L1: SDIP Authentication<br/>Zero-trust verify<br/>Traffic segmentation
+    L1->>L1: Validate SDIP
+    L1->>L1: Zero-trust check
+    L1->>L2: Authenticated Request
+    
+    Note over L2: FX cost optimization<br/>Liquidity check<br/>SRI risk weighting<br/>Route calculation
+    L2->>L2: Calculate optimal route
+    L2->>L2: Check liquidity
+    L2->>L2: Apply SRI weighting
+    L2->>L3: Route Selected
+    
+    Note over L3: Hash-lock creation<br/>Dual-ledger posting<br/>Hash-lock verification
+    L3->>L3: Create hash-lock
+    L3->>SCB: Post to SCB Ledger
+    L3->>DBIS: Post to DBIS Ledger
+    SCB-->>L3: Confirmation
+    DBIS-->>L3: Confirmation
+    L3->>L3: Verify hash-lock
+    L3->>PI: Finality Confirmed
+```
+
+**ASCII Diagram (Legacy)**:
+```
+┌─────────────┐
+│   Payment   │
+│  Initiator  │
+└──────┬──────┘
+       │
+       │ 1. Payment Request
+       │    (PACS.008)
+       ▼
+┌─────────────────────────┐
+│  Layer 1: Sovereign      │
+│  Access Layer           │
+│  - SDIP Authentication   │
+│  - Zero-trust verify    │
+│  - Traffic segmentation │
+└──────┬──────────────────┘
+       │
+       │ 2. Authenticated
+       ▼
+┌─────────────────────────┐
+│  Layer 2: Global        │
+│  Switching Layer        │
+│  - FX cost optimization  │
+│  - Liquidity check      │
+│  - SRI risk weighting   │
+│  - Route calculation    │
+└──────┬──────────────────┘
+       │
+       │ 3. Route Selected
+       ▼
+┌─────────────────────────┐
+│  Layer 3: Finality      │
+│  Layer                   │
+│  - Hash-lock creation   │
+│  - SCB ledger post       │
+│  - DBIS ledger post      │
+│  - Hash-lock verify     │
+└──────┬──────────────────┘
+       │
+       │ 4. Finality Confirmed
+       ▼
+┌─────────────┐
+│  Payment    │
+│  Settled    │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Payment Initiation
+1. Payment initiator submits payment request via API or ISO 20022 message (PACS.008)
+2. GPN message handler receives and validates message format
+3. Extract payment details:
+   - Source account (debtorAccount)
+   - Destination account (creditorAccount)
+   - Amount and currency
+   - Payment priority
+   - Reference information
+
+**Code Reference**: `src/core/payments/payment.service.ts:18-73`
+
+### Step 2: Layer 1 - Sovereign Access Authentication
+1. Extract SDIP from request headers or message
+2. Verify SDIP signature using sovereign identity service
+3. Validate sovereign bank ID matches SDIP
+4. Check zero-trust authentication:
+   - Verify request signature
+   - Validate timestamp (prevent replay attacks)
+   - Check access permissions
+5. Segment traffic by sovereign identity
+
+**Code Reference**: `src/integration/api-gateway/middleware/auth.middleware.ts`
+
+### Step 3: Account Validation
+1. Lookup source account (debtorAccount) by account number
+2. Lookup destination account (creditorAccount) by account number
+3. Verify both accounts exist and are active
+4. Check source account balance:
+   - Calculate available balance
+   - Verify sufficient funds for payment amount
+   - Consider any pending holds or reserves
+5. If insufficient balance, return error and terminate flow
+
+**Code Reference**: `src/core/accounts/account.service.ts`
+
+### Step 4: Layer 2 - Global Switching & Routing
+1. Calculate optimal route using:
+   - FX cost optimization
+   - Liquidity availability check
+   - SRI-based risk weighting
+   - Settlement mode (RTGS vs DNS)
+2. Determine settlement mode based on priority:
+   - RTGS for urgent/high-priority payments
+   - DNS for normal/deferred payments
+3. Select routing path:
+   - Direct SCB-to-SCB if same currency
+   - Via GSS if cross-currency
+   - Via SSU if optimal for cross-border
+4. Create payment routing record
+
+**Code Reference**: `src/core/settlement/sire/sire-routing.service.ts`
+
+### Step 5: Layer 3 - Finality & Settlement
+1. Create hash-lock for atomic settlement:
+   - Generate commitment hash
+   - Store hash-lock record
+2. Post to SCB sovereign ledger:
+   - Create debit entry on source account
+   - Create credit entry on destination account
+   - Generate sovereign ledger hash
+3. Post to DBIS master ledger:
+   - Create corresponding entries
+   - Generate DBIS ledger hash
+4. Verify hash-lock match:
+   - Compare sovereign and DBIS hashes
+   - Verify dual-ledger commit
+5. Mark payment as settled
+
+**Code Reference**: 
+- `src/core/settlement/gss/gss-master-ledger.service.ts:35-96`
+- `src/core/ledger/ledger-lifecycle.service.ts:44-139`
+
+### Step 6: Confirmation & Notification
+1. Generate payment status report (PACS.002)
+2. Send confirmation to payment initiator
+3. Notify destination bank (if different sovereign)
+4. Update payment status in database
+5. Log settlement event
+
+## Error Handling
+
+### Error: Account Not Found
+- **Detection**: Account lookup returns null
+- **Action**: Return error code `NOT_FOUND`
+- **Recovery**: Terminate flow, notify initiator
+
+### Error: Insufficient Balance
+- **Detection**: Available balance < payment amount
+- **Action**: Return error code `VALIDATION_ERROR`
+- **Recovery**: Terminate flow, suggest alternative payment methods
+
+### Error: Authentication Failure
+- **Detection**: SDIP verification fails
+- **Action**: Return error code `UNAUTHORIZED`
+- **Recovery**: Terminate flow, log security event
+
+### Error: Routing Failure
+- **Detection**: No valid route found
+- **Action**: Return error code `ROUTING_ERROR`
+- **Recovery**: Retry with alternative routing, escalate if persistent
+
+### Error: Dual-Ledger Commit Failure
+- **Detection**: Hash-lock verification fails
+- **Action**: Rollback both ledger entries
+- **Recovery**: 
+  - Mark payment as failed
+  - Create reconciliation record
+  - Notify operations team
+
+## Integration Points
+
+### Related Services
+- **Payment Service**: `src/core/payments/payment.service.ts`
+- **Account Service**: `src/core/accounts/account.service.ts`
+- **Ledger Service**: `src/core/ledger/ledger.service.ts`
+- **GSS Master Ledger**: `src/core/settlement/gss/gss-master-ledger.service.ts`
+- **SIRE Routing**: `src/core/settlement/sire/sire-routing.service.ts`
+- **Identity Service**: `src/core/cbdc/interoperability/cim-identity.service.ts`
+
+### API Endpoints
+- `POST /api/v1/gpn/authenticate` - Layer 1 authentication
+- `POST /api/v1/gpn/route` - Layer 2 routing
+- `POST /api/v1/gpn/finality` - Layer 3 finality verification
+- `POST /api/v1/gpn/message/pacs008` - ISO 20022 message handling
+
+### Database Models
+- `GpnPayment` - Payment routing records
+- `GpnRoute` - Routing paths with cost/risk metrics
+- `GpnSettlementLock` - Hash-lock records for finality
+
+## Performance Metrics
+
+- **Layer 1 (Authentication)**: < 50ms target
+- **Layer 2 (Routing)**: < 100ms target
+- **Layer 3 (Finality)**: < 200ms target
+- **Total End-to-End**: < 350ms target
+- **Throughput**: 10,000+ payments/second per node
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Authentication Checkpoints
+1. SDIP signature verification (Layer 1)
+2. Request signature validation
+3. Timestamp verification (replay attack prevention)
+4. Access permission checks
+
+### Authorization
+- Sovereign bank must have active status
+- Account must have transfer permissions
+- Payment amount within policy limits
+
+### Data Protection
+- All messages encrypted in transit (TLS 1.3)
+- Sensitive data encrypted at rest
+- Audit logging for all operations
+
+## Testing Scenarios
+
+### Happy Path
+1. Valid payment request with sufficient balance
+2. Successful authentication
+3. Successful routing
+4. Successful dual-ledger commit
+5. Payment settled within SLA
+
+### Error Scenarios
+1. Invalid SDIP signature
+2. Account not found
+3. Insufficient balance
+4. Routing failure
+5. Dual-ledger commit failure
+6. Network timeout
+
+### Edge Cases
+1. Concurrent payments to same account
+2. Maximum payment amount
+3. Minimum payment amount
+4. Cross-currency payments
+5. Offline destination bank
+
+## Recommendations
+
+### Error Handling Strategies
+
+**Priority: High**
+
+1. **Retry Mechanisms**
+   - **Description**: Implement intelligent retry logic for transient failures
+   - **Implementation**: Use exponential backoff, maximum retry limits, circuit breaker pattern
+   - **Impact**: Improves system resilience and reduces manual intervention
+   - **Dependencies**: Retry middleware, circuit breaker library
+
+2. **Idempotency Keys**
+   - **Description**: Ensure payment requests are idempotent
+   - **Implementation**: Generate unique idempotency keys, check for duplicate requests, return same response for duplicates
+   - **Impact**: Prevents duplicate payments and enables safe retries
+   - **Dependencies**: Idempotency key storage, request deduplication service
+
+3. **Compensation Transactions**
+   - **Description**: Implement compensation for failed payments
+   - **Implementation**: Track payment state, implement rollback procedures, notify parties of failures
+   - **Impact**: Ensures financial consistency and proper error recovery
+   - **Dependencies**: State tracking system, compensation service
+
+### Performance Optimization
+
+**Priority: High**
+
+1. **Payment Batching**
+   - **Description**: Batch multiple payments for efficiency
+   - **Implementation**: Collect payments in time windows, batch process, optimize database writes
+   - **Impact**: Reduces database load and improves throughput
+   - **Dependencies**: Batching service, batch processing framework
+
+2. **Caching Strategy**
+   - **Description**: Cache frequently accessed data
+   - **Implementation**: Cache account balances, FX rates, routing tables, use TTL-based invalidation
+   - **Impact**: Reduces database queries and improves response times
+   - **Dependencies**: Caching infrastructure (Redis), cache invalidation service
+
+3. **Async Processing**
+   - **Description**: Process non-critical operations asynchronously
+   - **Implementation**: Use message queues for notifications, reporting, audit logging
+   - **Impact**: Improves API response times and system scalability
+   - **Dependencies**: Message queue infrastructure (Kafka, RabbitMQ)
+
+### Security Hardening
+
+**Priority: Critical**
+
+1. **Request Signature Verification**
+   - **Description**: Verify all payment requests are properly signed
+   - **Implementation**: Use HSM-backed signatures, verify signatures on all requests, reject unsigned requests
+   - **Impact**: Prevents unauthorized payment requests
+   - **Dependencies**: HSM infrastructure, signature verification service
+
+2. **Rate Limiting**
+   - **Description**: Implement per-sovereign rate limiting
+   - **Implementation**: Track request rates, enforce limits, alert on violations
+   - **Impact**: Prevents abuse and ensures fair resource allocation
+   - **Dependencies**: Rate limiting middleware, monitoring system
+
+3. **Audit Logging**
+   - **Description**: Comprehensive audit trail for all payments
+   - **Implementation**: Log all payment operations, store in tamper-proof storage, enable audit queries
+   - **Impact**: Enables compliance and forensic analysis
+   - **Dependencies**: Audit logging service, secure storage
+
+### Monitoring Points
+
+**Priority: High**
+
+1. **Payment Latency Monitoring**
+   - Monitor time at each layer (L1, L2, L3)
+   - Alert on SLA violations
+   - Track p50, p95, p99 latencies
+
+2. **Error Rate Monitoring**
+   - Track error rates by error type
+   - Monitor authentication failures
+   - Alert on error rate spikes
+
+3. **Throughput Monitoring**
+   - Track payments per second
+   - Monitor queue depths
+   - Alert on capacity issues
+
+### Testing Approaches
+
+**Priority: Medium**
+
+1. **Load Testing**
+   - Test system under expected load
+   - Identify bottlenecks
+   - Validate SLA compliance
+
+2. **Chaos Engineering**
+   - Test failure scenarios
+   - Validate failover mechanisms
+   - Ensure system resilience
+
+3. **Security Testing**
+   - Penetration testing
+   - Fuzz testing
+   - Vulnerability scanning
+
+---
+
+**Related Flows**:
+- [GSS Settlement Flow](./gss-settlement-flow.md)
+- [M-RTGS Settlement Flow](./m-rtgs-settlement-flow.md)
+- [Atomic Settlement Flow](./atomic-settlement-flow.md)
+
--- a/docs/flows/gql-quantum-ledger-flow.md
+++ b/docs/flows/gql-quantum-ledger-flow.md
@@ -0,0 +1,36 @@
+# Gql Quantum Ledger Flow
+
+## Overview
+
+This flow documents the gql quantum ledger flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/gss-settlement-flow.md
+++ b/docs/flows/gss-settlement-flow.md
@@ -0,0 +1,259 @@
+# GSS Settlement Flow
+
+## Overview
+
+The Global Settlement System (GSS) implements a four-layer architecture for sovereign-grade settlement: Layer 1 (Sovereign), Layer 2 (DBIS Master), Layer 3 (Smart Clearing Fabric), and Layer 4 (Finality & Irreversibility). This flow documents the dual-ledger synchronization process.
+
+## Prerequisites
+
+- Source and destination banks are registered SCBs
+- Valid sovereign settlement node (SSN) configuration
+- Source and destination accounts exist
+- Sufficient balance in source account
+- Sovereign signature available (if required)
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ Settlement  │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Settlement Entry
+       ▼
+┌─────────────────────────┐
+│ Layer 1: Sovereign      │
+│ Ledger Posting          │
+│  - Account lookup        │
+│  - Debit/Credit entries  │
+│  - Generate hash         │
+└──────┬──────────────────┘
+       │
+       │ 2. Sovereign Hash
+       ▼
+┌─────────────────────────┐
+│ Layer 2: DBIS Master    │
+│ Ledger Posting          │
+│  - Master ledger entry  │
+│  - Generate hash         │
+└──────┬──────────────────┘
+       │
+       │ 3. DBIS Hash
+       ▼
+┌─────────────────────────┐
+│ Layer 3: Signature      │
+│ Validation (if provided) │
+│  - HSM verification      │
+│  - Identity check        │
+└──────┬──────────────────┘
+       │
+       │ 4. Validated
+       ▼
+┌─────────────────────────┐
+│ Layer 4: Master Entry   │
+│ Creation                 │
+│  - Dual-ledger commit   │
+│  - Status: settled       │
+└──────┬──────────────────┘
+       │
+       │ 5. Finality
+       ▼
+┌─────────────┐
+│ Settlement  │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Settlement Entry Creation
+1. Receive settlement request with:
+   - Source bank ID
+   - Destination bank ID
+   - Amount and currency
+   - Asset type
+   - Optional sovereign signature
+2. Generate unique entry ID: `GSS-ENTRY-{uuid}`
+3. Validate node configuration for source bank
+4. Verify both banks are active SCBs
+
+**Code Reference**: `src/core/settlement/gss/gss-master-ledger.service.ts:35-38`
+
+### Step 2: Layer 1 - Sovereign Ledger Posting
+1. Lookup source accounts:
+   - Filter by sovereign bank ID
+   - Match currency code and asset type
+   - Select active account
+2. Lookup destination accounts:
+   - Filter by sovereign bank ID
+   - Match currency code and asset type
+   - Select active account
+3. Post double-entry to sovereign ledger:
+   - Debit source account
+   - Credit destination account
+   - Use ledger ID: `Sovereign_{sourceBankId}`
+   - Transaction type: `Type_A`
+4. Retrieve ledger entry and extract block hash
+5. Store sovereign ledger hash
+
+**Code Reference**: `src/core/settlement/gss/gss-master-ledger.service.ts:101-150`
+
+### Step 3: Layer 2 - DBIS Master Ledger Posting
+1. Lookup source accounts (same as Step 2)
+2. Lookup destination accounts (same as Step 2)
+3. Post double-entry to DBIS master ledger:
+   - Debit source account
+   - Credit destination account
+   - Use ledger ID: `Master`
+   - Transaction type: `Type_A`
+   - Metadata: `{ gssEntry: true, masterLedger: true }`
+4. Retrieve ledger entry and extract block hash
+5. Store DBIS ledger hash
+
+**Code Reference**: `src/core/settlement/gss/gss-master-ledger.service.ts:155-203`
+
+### Step 4: Layer 3 - Sovereign Signature Validation (if provided)
+1. Check if sovereign signature is provided
+2. If provided:
+   - Lookup sovereign identity by bank ID
+   - Verify identity type is 'Settlement'
+   - Validate signature using HSM (in production)
+   - Verify signature matches entry data
+3. If validation fails, throw error and rollback
+
+**Code Reference**: `src/core/settlement/gss/gss-master-ledger.service.ts:208-232`
+
+### Step 5: Layer 4 - Master Entry Creation & Finality
+1. Create GSS master ledger entry with:
+   - Entry ID
+   - Node ID
+   - Source and destination bank IDs
+   - Amount, currency, asset type
+   - Sovereign signature (if provided)
+   - Dual-ledger commit flag: `true`
+   - Sovereign ledger hash
+   - DBIS ledger hash
+   - Status: `settled`
+   - Committed and settled timestamps
+2. Verify dual-ledger synchronization:
+   - Both hashes exist
+   - Both ledger entries exist
+   - Dual-commit flag is true
+3. Return dual-ledger result
+
+**Code Reference**: `src/core/settlement/gss/gss-master-ledger.service.ts:52-77`
+
+### Step 6: Error Handling (if any step fails)
+1. If error occurs after Step 1:
+   - Create failed entry record
+   - Set dual-ledger commit: `false`
+   - Set status: `failed`
+   - Log error details
+2. Rollback any partial ledger entries
+3. Throw error to caller
+
+**Code Reference**: `src/core/settlement/gss/gss-master-ledger.service.ts:78-95`
+
+## Error Handling
+
+### Error: Accounts Not Found
+- **Detection**: Account lookup returns empty array
+- **Action**: Throw error "Accounts not found for sovereign ledger posting"
+- **Recovery**: Verify account configuration, retry with correct parameters
+
+### Error: Sovereign Signature Invalid
+- **Detection**: Signature validation fails
+- **Action**: Throw error "Sovereign identity not found" or "Signature invalid"
+- **Recovery**: Request new signature, verify HSM configuration
+
+### Error: Dual-Ledger Mismatch
+- **Detection**: Hashes don't match or entries missing
+- **Action**: Mark entry as failed, create reconciliation record
+- **Recovery**: Manual reconciliation process, verify ledger integrity
+
+### Error: Node Configuration Missing
+- **Detection**: SSN not configured for source bank
+- **Action**: Return error, prevent settlement
+- **Recovery**: Configure SSN, retry settlement
+
+## Integration Points
+
+### Related Services
+- **GSS Master Ledger Service**: `src/core/settlement/gss/gss-master-ledger.service.ts`
+- **Ledger Service**: `src/core/ledger/ledger.service.ts`
+- **Account Service**: `src/core/accounts/account.service.ts`
+- **GSS Architecture Service**: `src/core/settlement/gss/gss-architecture.service.ts`
+
+### API Endpoints
+- `POST /api/v1/gss/settlement/execute` - Execute GSS settlement
+- `GET /api/v1/gss/master-ledger/entries` - Query master ledger entries
+- `GET /api/v1/gss/master-ledger/entries/:entryId` - Get specific entry
+- `POST /api/v1/gss/master-ledger/verify` - Verify dual-ledger sync
+
+### Database Models
+- `GssMasterLedger` - Master ledger entries
+- `SovereignSettlementNode` - SSN configuration
+- `LedgerEntry` - Individual ledger entries
+
+## Performance Metrics
+
+- **Layer 1 (Sovereign Posting)**: < 100ms target
+- **Layer 2 (DBIS Posting)**: < 100ms target
+- **Layer 3 (Signature Validation)**: < 50ms target (if required)
+- **Layer 4 (Master Entry)**: < 50ms target
+- **Total End-to-End**: < 300ms target
+- **Throughput**: 5,000+ settlements/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Authentication
+- Sovereign bank must be registered and active
+- Node ID must match configured SSN
+
+### Authorization
+- Source bank must have settlement permissions
+- Accounts must be active and accessible
+
+### Data Integrity
+- Dual-ledger commit ensures consistency
+- Hash verification prevents tampering
+- Sovereign signatures provide non-repudiation
+
+### Audit Trail
+- All entries logged with timestamps
+- Dual-ledger hashes provide proof
+- Failed entries tracked for reconciliation
+
+## Testing Scenarios
+
+### Happy Path
+1. Valid settlement request
+2. Successful sovereign ledger posting
+3. Successful DBIS master ledger posting
+4. Valid sovereign signature (if provided)
+5. Successful master entry creation
+6. Dual-ledger verification passes
+
+### Error Scenarios
+1. Accounts not found
+2. Sovereign signature invalid
+3. Dual-ledger mismatch
+4. Node configuration missing
+5. Network timeout during posting
+
+### Edge Cases
+1. Concurrent settlements to same account
+2. Maximum settlement amount
+3. Settlement with missing signature
+4. Settlement during ledger maintenance
+5. Cross-currency settlements
+
+---
+
+**Related Flows**:
+- [GPN Payment Flow](./gpn-payment-flow.md)
+- [Atomic Settlement Flow](./atomic-settlement-flow.md)
+- [M-RTGS Settlement Flow](./m-rtgs-settlement-flow.md)
+
--- a/docs/flows/id-slg-liquidity-flow.md
+++ b/docs/flows/id-slg-liquidity-flow.md
@@ -0,0 +1,36 @@
+# Id Slg Liquidity Flow
+
+## Overview
+
+This flow documents the id slg liquidity flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/identity-verification-flow.md
+++ b/docs/flows/identity-verification-flow.md
@@ -0,0 +1,36 @@
+# Identity Verification Flow
+
+## Overview
+
+This flow documents the identity verification flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/iso20022-message-flow.md
+++ b/docs/flows/iso20022-message-flow.md
@@ -0,0 +1,36 @@
+# Iso20022 Message Flow
+
+## Overview
+
+This flow documents the iso20022 message flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/kyc-enforcement-flow.md
+++ b/docs/flows/kyc-enforcement-flow.md
@@ -0,0 +1,36 @@
+# Kyc Enforcement Flow
+
+## Overview
+
+This flow documents the kyc enforcement flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/m-rtgs-settlement-flow.md
+++ b/docs/flows/m-rtgs-settlement-flow.md
@@ -0,0 +1,271 @@
+# M-RTGS Settlement Flow
+
+## Overview
+
+The Multi-Asset RTGS System (M-RTGS) provides instantaneous settlement (< 100ms target) for multiple asset types (fiat, CBDC, SSU, commodities, securities) in a single synchronized settlement cycle. This flow documents the priority queue management and multi-asset settlement process.
+
+## Prerequisites
+
+- Payment request with valid source and destination accounts
+- Sufficient balance/position in source account
+- Asset type supported by M-RTGS
+- M-RTGS service operational
+- Queue manager initialized
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│  Payment    │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Add to Queue
+       ▼
+┌─────────────────────────┐
+│ Queue Manager           │
+│  - Calculate priority    │
+│  - Priority = systemic  │
+│    + fx_cost +          │
+│    liquidity + SRI      │
+└──────┬──────────────────┘
+       │
+       │ 2. Priority Score
+       ▼
+┌─────────────────────────┐
+│ Queue Processing        │
+│  - Tier 1: Sovereign    │
+│  - Tier 2: Interbank    │
+│  - Tier 3: Retail       │
+└──────┬──────────────────┘
+       │
+       │ 3. Process Next
+       ▼
+┌─────────────────────────┐
+│ Risk Monitor            │
+│  - Velocity check        │
+│  - Liquidity check      │
+│  - FX slip check        │
+└──────┬──────────────────┘
+       │
+       │ 4. Risk Cleared
+       ▼
+┌─────────────────────────┐
+│ Multi-Asset Settlement  │
+│  - Multi-ledger sync    │
+│  - < 100ms target       │
+│  - Status tracking      │
+└──────┬──────────────────┘
+       │
+       │ 5. Settled
+       ▼
+┌─────────────┐
+│ Settlement  │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Payment Queue Addition
+1. Receive payment request with:
+   - Source bank ID
+   - Destination bank ID
+   - Amount and currency
+   - Asset type (fiat, CBDC, SSU, commodity, security)
+   - Payment priority
+2. Calculate priority score:
+   ```
+   priority = systemic_value + fx_cost_penalty + liquidity_weight + SRI_adjustment
+   ```
+3. Determine priority tier:
+   - **Tier 1**: Sovereign & systemic transactions
+   - **Tier 2**: Interbank transactions
+   - **Tier 3**: Retail CBDC traffic during peak hours
+4. Add payment to appropriate queue with priority score
+5. Generate queue entry ID
+
+**Code Reference**: `src/core/settlement/m-rtgs/` (queue manager service)
+
+### Step 2: Queue Processing
+1. Queue manager selects next payment based on:
+   - Priority tier
+   - Priority score within tier
+   - First-in-first-out for same priority
+2. Lock payment entry to prevent concurrent processing
+3. Verify payment still valid:
+   - Source account still active
+   - Sufficient balance available
+   - Destination account still active
+
+### Step 3: Risk Monitoring
+1. Check transaction velocity:
+   - Count transactions from source in time window
+   - Verify within velocity limits
+2. Check liquidity congestion:
+   - Verify sufficient liquidity in system
+   - Check for liquidity bottlenecks
+3. Check FX slip (if cross-currency):
+   - Verify FX rate stability
+   - Check for excessive volatility
+4. Check commodity price shocks (if commodity asset):
+   - Verify commodity price stability
+5. Check CBDC routing patterns:
+   - Verify no abnormal routing detected
+6. If any risk check fails, flag payment and escalate
+
+**Code Reference**: `src/core/settlement/m-rtgs/` (risk monitor service)
+
+### Step 4: Multi-Asset Settlement Execution
+1. Determine settlement method based on asset type:
+   - **Fiat**: Standard ledger posting
+   - **CBDC**: CBDC ledger posting
+   - **SSU**: SSU transaction service
+   - **Commodity**: CDT settlement service
+   - **Security**: Security token settlement
+2. Execute multi-ledger synchronization:
+   - Post to source ledger
+   - Post to destination ledger
+   - Post to master ledger (if required)
+3. Monitor settlement time:
+   - Start timer at settlement initiation
+   - Target: < 100ms total time
+   - Log if exceeds target
+4. Update payment status:
+   - Mark as "settling" during execution
+   - Mark as "settled" on completion
+   - Record settlement timestamp
+
+**Code Reference**: 
+- `src/core/settlement/m-rtgs/` (settlement service)
+- `src/core/ledger/ledger.service.ts`
+- `src/core/settlement/ssu/ssu-service.ts`
+- `src/core/commodities/cbds/cdt-settlement.service.ts`
+
+### Step 5: MACE Integration (if collateralized)
+1. If payment requires collateral:
+   - Calculate required initial margin (IM):
+     ```
+     IM = exposure * volatility * SRI_factor
+     ```
+   - Verify collateral availability
+   - Allocate collateral via MACE engine
+2. Update collateral positions
+3. Monitor margin requirements
+
+**Code Reference**: `src/core/settlement/m-rtgs/` (MACE integration service)
+
+### Step 6: Settlement Confirmation
+1. Verify all ledger entries posted successfully
+2. Generate settlement confirmation
+3. Update queue entry status
+4. Release queue lock
+5. Notify payment initiator
+6. Log settlement event with metrics
+
+## Error Handling
+
+### Error: Insufficient Balance
+- **Detection**: Balance check fails
+- **Action**: Remove from queue, return error
+- **Recovery**: Notify initiator, suggest alternative
+
+### Error: Risk Check Failed
+- **Detection**: Risk monitor flags payment
+- **Action**: Hold payment, escalate to operations
+- **Recovery**: Manual review, adjust risk parameters if needed
+
+### Error: Settlement Timeout
+- **Detection**: Settlement exceeds 100ms target
+- **Action**: Log warning, continue processing
+- **Recovery**: Investigate performance bottleneck
+
+### Error: Multi-Ledger Sync Failure
+- **Detection**: One or more ledger posts fail
+- **Action**: Rollback all ledger entries
+- **Recovery**: Retry settlement, escalate if persistent
+
+### Error: Queue Lock Timeout
+- **Detection**: Payment locked too long
+- **Action**: Release lock, retry or fail
+- **Recovery**: Investigate deadlock conditions
+
+## Integration Points
+
+### Related Services
+- **M-RTGS Queue Manager**: `src/core/settlement/m-rtgs/` (queue manager)
+- **M-RTGS Settlement Service**: `src/core/settlement/m-rtgs/` (settlement)
+- **M-RTGS Risk Monitor**: `src/core/settlement/m-rtgs/` (risk monitor)
+- **M-RTGS MACE Integration**: `src/core/settlement/m-rtgs/` (MACE)
+- **Ledger Service**: `src/core/ledger/ledger.service.ts`
+- **SSU Service**: `src/core/settlement/ssu/ssu-service.ts`
+- **CDT Settlement**: `src/core/commodities/cbds/cdt-settlement.service.ts`
+
+### API Endpoints
+- `POST /api/v1/m-rtgs/queue/add` - Add payment to queue
+- `GET /api/v1/m-rtgs/queue/next` - Get next payment from queue
+- `POST /api/v1/m-rtgs/settle` - Execute settlement
+- `POST /api/v1/m-rtgs/risk/monitor` - Risk monitoring
+
+### Database Models
+- `MrtgsQueue` - Queue entries with priority scores
+- `MrtgsSettlement` - Settlement records with multi-asset support
+- `MrtgsRiskAlert` - Risk monitoring alerts
+
+## Performance Metrics
+
+- **Queue Addition**: < 10ms target
+- **Priority Calculation**: < 5ms target
+- **Risk Monitoring**: < 20ms target
+- **Settlement Execution**: < 100ms target (total)
+- **Total End-to-End**: < 135ms target
+- **Throughput**: 50,000+ payments/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### Access Control
+- Only authorized banks can submit payments
+- Queue access restricted to M-RTGS service
+
+### Data Integrity
+- Queue entries locked during processing
+- Multi-ledger synchronization ensures consistency
+- Settlement timestamps provide audit trail
+
+### Risk Controls
+- Real-time velocity monitoring
+- Liquidity congestion detection
+- FX and commodity price shock detection
+
+## Testing Scenarios
+
+### Happy Path
+1. Valid payment request
+2. Successful queue addition
+3. Priority calculation correct
+4. Risk checks pass
+5. Settlement completes < 100ms
+6. All ledgers synchronized
+
+### Error Scenarios
+1. Insufficient balance
+2. Risk check failure
+3. Settlement timeout
+4. Multi-ledger sync failure
+5. Queue lock timeout
+
+### Edge Cases
+1. Maximum priority payment
+2. Minimum priority payment
+3. All asset types
+4. Concurrent high-priority payments
+5. System under heavy load
+
+---
+
+**Related Flows**:
+- [GPN Payment Flow](./gpn-payment-flow.md)
+- [GSS Settlement Flow](./gss-settlement-flow.md)
+- [Atomic Settlement Flow](./atomic-settlement-flow.md)
+
--- a/docs/flows/multiversal-settlement-flow.md
+++ b/docs/flows/multiversal-settlement-flow.md
@@ -0,0 +1,36 @@
+# Multiversal Settlement Flow
+
+## Overview
+
+This flow documents the multiversal settlement flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/offline-capsule-flow.md
+++ b/docs/flows/offline-capsule-flow.md
@@ -0,0 +1,36 @@
+# Offline Capsule Flow
+
+## Overview
+
+This flow documents the offline capsule flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/omega-layer-settlement-flow.md
+++ b/docs/flows/omega-layer-settlement-flow.md
@@ -0,0 +1,36 @@
+# Omega Layer Settlement Flow
+
+## Overview
+
+This flow documents the omega layer settlement flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/qps-legacy-bridge-flow.md
+++ b/docs/flows/qps-legacy-bridge-flow.md
@@ -0,0 +1,36 @@
+# Qps Legacy Bridge Flow
+
+## Overview
+
+This flow documents the qps legacy bridge flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/regtech-monitoring-flow.md
+++ b/docs/flows/regtech-monitoring-flow.md
@@ -0,0 +1,36 @@
+# Regtech Monitoring Flow
+
+## Overview
+
+This flow documents the regtech monitoring flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/ssu-atomic-settlement-flow.md
+++ b/docs/flows/ssu-atomic-settlement-flow.md
@@ -0,0 +1,102 @@
+# SSU Atomic Settlement Flow
+
+## Overview
+
+SSU atomic settlement uses Synthetic Settlement Units for cross-border settlement with atomic execution guarantees. This flow documents the complete SSU-based settlement process.
+
+## Prerequisites
+
+- SSU exists and is active
+- Sufficient SSU balance
+- Source and destination banks registered
+- Atomic settlement service operational
+
+## Visual Flow Diagram
+
+```
+┌─────────────┐
+│ SSU         │
+│ Settlement  │
+│  Request    │
+└──────┬──────┘
+       │
+       │ 1. Verify SSU
+       ▼
+┌─────────────────────────┐
+│ Verify SSU & Balance   │
+│  - SSU lookup           │
+│  - Balance check        │
+└──────┬──────────────────┘
+       │
+       │ 2. Create Transaction
+       ▼
+┌─────────────────────────┐
+│ Create SSU Transaction  │
+│  - Transaction ID       │
+│  - Settlement type      │
+└──────┬──────────────────┘
+       │
+       │ 3. Execute Atomic Swap
+       ▼
+┌─────────────────────────┐
+│ Execute Atomic Swap     │
+│  - Verify commitments   │
+│  - Execute on both sides│
+└──────┬──────────────────┘
+       │
+       │ 4. Complete
+       ▼
+┌─────────────┐
+│ Settlement  │
+│  Complete   │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Step 1: Verify SSU
+1. Lookup SSU by ID
+2. Verify SSU is active
+3. Check SSU balance
+4. Verify sufficient balance
+
+**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:99-126`
+
+### Step 2: Create Transaction
+1. Create SSU transaction record
+2. Set transaction type: `settle`
+3. Link to source and destination banks
+4. Store transaction ID
+
+**Code Reference**: `src/core/settlement/ssu/ssu-transaction.service.ts`
+
+### Step 3: Execute Atomic Swap
+1. Create commitments for both sides
+2. Verify commitments match
+3. Execute swap atomically
+4. Verify execution success
+
+**Code Reference**: `src/core/settlement/isn/atomic-settlement.service.ts`
+
+## Error Handling
+
+- SSU not found: Return error
+- Insufficient balance: Return error
+- Atomic swap failure: Rollback, mark failed
+
+## Integration Points
+
+- SSU Service: `src/core/settlement/ssu/ssu-service.ts`
+- Atomic Settlement Service: `src/core/settlement/isn/atomic-settlement.service.ts`
+
+## Performance Metrics
+
+- Total End-to-End: < 150ms target
+- Throughput: 5,000+ settlements/second
+
+---
+
+**Related Flows**:
+- [SSU Mint Burn Flow](./ssu-mint-burn-flow.md)
+- [Atomic Settlement Flow](./atomic-settlement-flow.md)
+
--- a/docs/flows/ssu-mint-burn-flow.md
+++ b/docs/flows/ssu-mint-burn-flow.md
@@ -0,0 +1,312 @@
+# SSU Mint Burn Flow
+
+## Overview
+
+The Synthetic Settlement Unit (SSU) is a stabilized cross-border settlement asset with composition: 40% currency, 30% commodity, 20% CBDC, 10% LAM. This flow documents the minting and burning processes, including composition calculation and liquidity verification.
+
+## Prerequisites
+
+- SSU exists or can be created (default SSU)
+- Sufficient liquidity in underlying assets (for minting)
+- Valid mint/burn request
+- SSU service operational
+- Composition service available
+
+## Visual Flow Diagram
+
+### Minting Flow
+
+```
+┌─────────────┐
+│ Mint Request│
+└──────┬──────┘
+       │
+       │ 1. Get/Create SSU
+       ▼
+┌─────────────────────────┐
+│ Get or Create Default   │
+│  SSU                     │
+│  - Lookup active SSU     │
+│  - Create if not exists  │
+└──────┬──────────────────┘
+       │
+       │ 2. Verify Liquidity
+       ▼
+┌─────────────────────────┐
+│ Verify Liquidity for    │
+│  Minting                 │
+│  - Check underlying      │
+│  - Verify sufficient     │
+└──────┬──────────────────┘
+       │
+       │ 3. Calculate Composition
+       ▼
+┌─────────────────────────┐
+│ Calculate SSU            │
+│  Composition              │
+│  - 40% currency          │
+│  - 30% commodity         │
+│  - 20% CBDC              │
+│  - 10% LAM               │
+└──────┬──────────────────┘
+       │
+       │ 4. Create Transaction
+       ▼
+┌─────────────────────────┐
+│ Create Mint Transaction │
+│  - Transaction ID        │
+│  - Amount                │
+│  - Type: mint            │
+└──────┬──────────────────┘
+       │
+       │ 5. Complete
+       ▼
+┌─────────────┐
+│ SSU Minted  │
+└─────────────┘
+```
+
+### Burning Flow
+
+```
+┌─────────────┐
+│ Burn Request│
+└──────┬──────┘
+       │
+       │ 1. Verify SSU
+       ▼
+┌─────────────────────────┐
+│ Verify SSU Exists        │
+│  - Lookup SSU by ID       │
+│  - Check status: active   │
+└──────┬──────────────────┘
+       │
+       │ 2. Create Transaction
+       ▼
+┌─────────────────────────┐
+│ Create Burn Transaction  │
+│  - Transaction ID        │
+│  - Amount                │
+│  - Type: burn            │
+└──────┬──────────────────┘
+       │
+       │ 3. Complete
+       ▼
+┌─────────────┐
+│ SSU Burned  │
+└─────────────┘
+```
+
+## Step-by-Step Process
+
+### Minting Process
+
+#### Step 1: Get or Create Default SSU
+1. Receive mint request with:
+   - Amount to mint
+   - Trigger bank ID (optional)
+   - Transaction ID (optional)
+2. Lookup default SSU:
+   - Search for SSU with name: "DBIS Global SSU"
+   - Filter by status: `active`
+3. If SSU doesn't exist:
+   - Generate SSU ID: `SSU-{uuid}`
+   - Create SSU record:
+     - SSU ID
+     - SSU name: "DBIS Global SSU"
+     - Description: "DBIS Synthetic Settlement Unit - Global settlement asset"
+     - Underlying assets: empty array (initialized later)
+     - Status: `active`
+   - Initialize composition via composition service
+4. Return SSU (existing or newly created)
+
+**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:46-208`
+
+#### Step 2: Verify Liquidity for Minting
+1. Validate mint amount:
+   - Convert to Decimal
+   - Verify: `amount > 0`
+   - If invalid, throw error: "Mint amount must be greater than zero"
+2. Verify underlying asset liquidity:
+   - In production: check liquidity pools for:
+     - 40% currency reserves
+     - 30% commodity reserves
+     - 20% CBDC reserves
+     - 10% LAM reserves
+   - Currently: assume liquidity available (simplified)
+3. If insufficient liquidity, throw error
+
+**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:213-221`
+
+#### Step 3: Calculate Composition
+1. Call composition service to calculate current composition:
+   - Pass SSU ID
+   - Service calculates based on:
+     - Current market values
+     - Reserve availability
+     - Target composition ratios
+2. Composition service returns:
+   - Currency percentage: 40%
+   - Commodity percentage: 30%
+   - CBDC percentage: 20%
+   - LAM percentage: 10%
+3. Store composition for this mint operation
+
+**Code Reference**: `src/core/settlement/ssu/ssu-composition.service.ts`
+
+#### Step 4: Create Mint Transaction
+1. Call SSU transaction service to create transaction:
+   - SSU ID
+   - Transaction type: `mint`
+   - Amount: mint amount
+   - Source bank ID: trigger bank ID (if provided)
+   - Settlement ID: transaction ID (if provided)
+2. Transaction service creates:
+   - Transaction ID
+   - Transaction record
+   - Links to SSU
+3. Update SSU balance (if tracked):
+   - In production: increment SSU total supply
+   - Currently: simplified (balance tracking)
+4. Return transaction ID
+
+**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:57-68`
+
+### Burning Process
+
+#### Step 1: Verify SSU Exists
+1. Receive burn request with:
+   - SSU ID
+   - Amount to burn
+   - Reason (optional)
+2. Lookup SSU by ID
+3. Verify SSU exists and status is `active`
+4. If not found or inactive, throw error: "SSU not found or not active"
+
+**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:74-94`
+
+#### Step 2: Create Burn Transaction
+1. Call SSU transaction service to create transaction:
+   - SSU ID
+   - Transaction type: `burn`
+   - Amount: burn amount
+2. Transaction service creates:
+   - Transaction ID
+   - Transaction record
+   - Links to SSU
+3. Update SSU balance (if tracked):
+   - In production: decrement SSU total supply
+   - Currently: simplified (balance tracking)
+4. Return transaction ID
+
+**Code Reference**: `src/core/settlement/ssu/ssu-service.ts:84-93`
+
+## Error Handling
+
+### Error: SSU Not Found
+- **Detection**: SSU lookup returns null
+- **Action**: Throw error "SSU not found or not active"
+- **Recovery**: Verify SSU ID, create SSU if needed
+
+### Error: SSU Inactive
+- **Detection**: SSU status is not `active`
+- **Action**: Throw error "SSU not found or not active"
+- **Recovery**: Activate SSU, retry
+
+### Error: Invalid Mint Amount
+- **Detection**: Amount <= 0
+- **Action**: Throw error "Mint amount must be greater than zero"
+- **Recovery**: Correct amount, retry
+
+### Error: Insufficient Liquidity
+- **Detection**: Underlying assets don't have sufficient liquidity
+- **Action**: Throw error, prevent minting
+- **Recovery**: Add liquidity to pools, retry
+
+### Error: Composition Calculation Failure
+- **Detection**: Composition service returns error
+- **Action**: Throw error, prevent minting
+- **Recovery**: Verify composition service, retry
+
+## Integration Points
+
+### Related Services
+- **SSU Service**: `src/core/settlement/ssu/ssu-service.ts`
+- **SSU Composition Service**: `src/core/settlement/ssu/ssu-composition.service.ts`
+- **SSU Transaction Service**: `src/core/settlement/ssu/ssu-transaction.service.ts`
+- **Liquidity Services**: GLP, ID-SLG for liquidity verification
+
+### API Endpoints
+- `POST /api/v1/ssu/mint` - Mint SSU
+- `POST /api/v1/ssu/burn` - Burn SSU
+- `GET /api/v1/ssu/:ssuId` - Get SSU details
+- `GET /api/v1/ssu` - List active SSUs
+
+### Database Models
+- `SyntheticSettlementUnit` - SSU records
+- `SsuTransaction` - SSU transaction records
+- `SsuComposition` - Composition records
+
+## Performance Metrics
+
+- **SSU Lookup/Creation**: < 10ms target
+- **Liquidity Verification**: < 20ms target
+- **Composition Calculation**: < 30ms target
+- **Transaction Creation**: < 10ms target
+- **Total End-to-End**: < 70ms target
+- **Throughput**: 5,000+ operations/second
+- **Availability**: 99.99% uptime target
+
+## Security Considerations
+
+### SSU Validation
+- Only active SSUs can be used
+- SSU ID verification prevents unauthorized access
+
+### Liquidity Verification
+- Ensures underlying assets available
+- Prevents over-minting
+- Maintains composition ratios
+
+### Transaction Tracking
+- All mint/burn operations logged
+- Transaction IDs provide audit trail
+- Links to source transactions
+
+## Testing Scenarios
+
+### Happy Path - Minting
+1. Valid mint request
+2. SSU exists or created
+3. Sufficient liquidity
+4. Composition calculated
+5. Transaction created
+6. SSU minted
+
+### Happy Path - Burning
+1. Valid burn request
+2. SSU exists and active
+3. Transaction created
+4. SSU burned
+
+### Error Scenarios
+1. SSU not found
+2. SSU inactive
+3. Invalid mint amount
+4. Insufficient liquidity
+5. Composition calculation failure
+
+### Edge Cases
+1. Maximum mint amount
+2. Minimum mint amount
+3. Mint with zero amount (should fail)
+4. Burn more than available
+5. Concurrent mint/burn operations
+
+---
+
+**Related Flows**:
+- [SSU Atomic Settlement Flow](./ssu-atomic-settlement-flow.md)
+- [FX/SSU Integration Flow](./fx-ssu-integration-flow.md)
+- [GLP Contribution Withdrawal Flow](./glp-contribution-withdrawal-flow.md)
+
--- a/docs/flows/swift-integration-flow.md
+++ b/docs/flows/swift-integration-flow.md
@@ -0,0 +1,36 @@
+# Swift Integration Flow
+
+## Overview
+
+This flow documents the swift integration flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/temporal-settlement-flow.md
+++ b/docs/flows/temporal-settlement-flow.md
@@ -0,0 +1,36 @@
+# Temporal Settlement Flow
+
+## Overview
+
+This flow documents the temporal settlement flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)
--- a/docs/flows/trlm-mesh-flow.md
+++ b/docs/flows/trlm-mesh-flow.md
@@ -0,0 +1,36 @@
+# Trlm Mesh Flow
+
+## Overview
+
+This flow documents the trlm mesh flow process.
+
+## Prerequisites
+
+- System components operational
+- Valid request parameters
+
+## Visual Flow Diagram
+
+```
+[Diagram to be added]
+```
+
+## Step-by-Step Process
+
+[Detailed steps to be documented]
+
+## Error Handling
+
+[Error scenarios to be documented]
+
+## Integration Points
+
+[Integration details to be documented]
+
+## Performance Metrics
+
+[Performance targets to be documented]
+
+---
+
+**Related Flows**: See [Flows Directory](./README.md)