Initial commit

docs/adr/0001-template.md

@@ -0,0 +1,46 @@
+# ADR-0001: Architecture Decision Record Template
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded]
+
+## Context
+Describe the issue motivating this decision or change. This is an open-ended section that can include:
+- Business context
+- Technical context
+- Constraints
+- Forces
+
+## Decision
+State the architectural decision that is being made. This should be stated clearly and concisely.
+
+## Consequences
+Describe the consequences of this decision, both positive and negative:
+
+### Positive
+- Benefit 1
+- Benefit 2
+
+### Negative
+- Drawback 1
+- Drawback 2
+
+### Risks
+- Risk 1
+- Risk 2
+
+## Alternatives Considered
+List alternative approaches that were considered:
+
+1. **Alternative 1**: Description
+   - Pros: ...
+   - Cons: ...
+
+2. **Alternative 2**: Description
+   - Pros: ...
+   - Cons: ...
+
+## References
+- Link to related documents
+- External resources
+- Related ADRs
+

docs/adr/0002-singleton-prisma-client.md

@@ -0,0 +1,117 @@
+# ADR-0002: Singleton Prisma Client Pattern
+
+## Status
+Accepted
+
+## Context
+The application was creating multiple `PrismaClient` instances across different service files. This led to:
+- Multiple database connection pools
+- Potential connection exhaustion
+- Inconsistent connection management
+- Difficulties in monitoring and debugging database connections
+
+## Decision
+Implement a singleton pattern for Prisma Client to ensure:
+- Single connection pool across the application
+- Proper connection lifecycle management
+- Graceful shutdown handling
+- Development hot-reload compatibility
+
+The singleton is implemented in `src/shared/database/prisma.ts` and exported for use across the application.
+
+## Consequences
+
+### Positive
+- Single connection pool reduces resource usage
+- Consistent connection management
+- Easier to monitor and debug
+- Proper cleanup on application shutdown
+- Works correctly with development hot-reload
+
+### Negative
+- Requires refactoring existing code (381 files identified)
+- All services must import from shared location
+- Potential for circular dependencies if not careful
+
+### Risks
+- Large refactoring effort required
+- Need to ensure all services are updated
+- Must maintain backward compatibility during migration
+
+## Decision Tree
+
+```mermaid
+graph TD
+    START[Need Database Connection Management]
+    
+    START --> Q1{Connection Pool<br/>Issues?}
+    Q1 -->|Yes| Q2{Refactoring<br/>Acceptable?}
+    Q1 -->|No| ALT1[Keep Multiple Clients]
+    
+    Q2 -->|Yes| Q3{Need DI<br/>Framework?}
+    Q2 -->|No| ALT1
+    
+    Q3 -->|No| DECISION[Singleton Pattern<br/>CHOSEN]
+    Q3 -->|Yes| ALT2[Dependency Injection]
+    
+    DECISION --> IMPL[Implement Singleton]
+    ALT1 --> RISK1[Connection Exhaustion Risk]
+    ALT2 --> COMPLEX[Increased Complexity]
+    
+    IMPL --> BENEFIT[Single Connection Pool<br/>Better Management]
+```
+
+## Alternatives Considered
+
+1. **Multiple Prisma Clients**: Keep current approach
+   - Pros: Simple, no refactoring needed
+   - Cons: Connection pool issues, resource waste
+
+2. **Dependency Injection**: Inject Prisma client
+   - Pros: Testable, flexible
+   - Cons: More complex, requires DI framework
+
+3. **Singleton Pattern**: Chosen approach
+   - Pros: Simple, effective, minimal changes
+   - Cons: Requires refactoring
+
+## Implementation
+- Created `src/shared/database/prisma.ts` with singleton pattern
+- Refactored critical services (ledger, fx, accounts, payments, etc.)
+- Remaining services to be refactored systematically
+
+## Recommendations
+
+**Priority: High**
+
+1. **Systematic Refactoring**
+   - **Description**: Complete refactoring of remaining services
+   - **Implementation**: 
+     - Refactor services incrementally
+     - Test each refactored service
+     - Monitor connection pool metrics
+   - **Impact**: Ensures consistent connection management across all services
+   - **Dependencies**: Test coverage, monitoring infrastructure
+
+2. **Connection Pool Monitoring**
+   - **Description**: Monitor connection pool usage
+   - **Implementation**: 
+     - Track active/idle connections
+     - Alert on pool exhaustion
+     - Optimize pool size based on load
+   - **Impact**: Prevents connection issues and enables optimization
+   - **Dependencies**: Monitoring system, metrics collection
+
+3. **Documentation Updates**
+   - **Description**: Document singleton pattern usage
+   - **Implementation**: 
+     - Update development guide
+     - Add code examples
+     - Document migration process
+   - **Impact**: Ensures new code follows pattern
+   - **Dependencies**: Documentation system
+
+## References
+- Prisma Best Practices: https://www.prisma.io/docs/guides/performance-and-optimization/connection-management
+- Node.js Connection Pooling: https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/
+

docs/adr/0003-environment-validation.md

@@ -0,0 +1,61 @@
+# ADR-0003: Environment Variable Validation at Startup
+
+## Status
+Accepted
+
+## Context
+The application was using environment variables without validation, leading to:
+- Runtime errors when required variables were missing
+- Security risks from weak or missing secrets
+- Difficult debugging when misconfigured
+- No clear error messages for configuration issues
+
+## Decision
+Implement environment variable validation that:
+- Runs at application startup
+- Validates all required variables
+- Provides clear error messages
+- Supports different validation rules per environment
+- Fails fast if critical variables are missing or invalid
+
+## Consequences
+
+### Positive
+- Early detection of configuration errors
+- Clear error messages guide developers
+- Prevents runtime failures from misconfiguration
+- Security improvements (validates JWT secret strength, CORS config)
+- Better developer experience
+
+### Negative
+- Application won't start if validation fails (by design)
+- Requires maintaining validation schema
+- Additional startup time (minimal)
+
+### Risks
+- Breaking changes if validation rules are too strict
+- Need to keep validation in sync with actual usage
+
+## Alternatives Considered
+
+1. **Runtime Validation**: Validate when variables are used
+   - Pros: More flexible
+   - Cons: Errors discovered late, harder to debug
+
+2. **Configuration File**: Use config file instead of env vars
+   - Pros: Type-safe, validated
+   - Cons: Doesn't work well with 12-factor app principles
+
+3. **Startup Validation**: Chosen approach
+   - Pros: Fail fast, clear errors, secure defaults
+   - Cons: None significant
+
+## Implementation
+- Created `src/shared/config/env-validator.ts`
+- Integrated into `src/index.ts` startup
+- Validates: DATABASE_URL, JWT_SECRET, ALLOWED_ORIGINS, etc.
+
+## References
+- 12-Factor App: https://12factor.net/config
+- Node.js Environment Variables: https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs
+

docs/adr/0004-authentication-strategy.md

@@ -0,0 +1,63 @@
+# ADR-0004: Zero-Trust Authentication Strategy
+
+## Status
+Accepted
+
+## Context
+The DBIS Core Banking System requires secure authentication for all API requests. Traditional authentication methods are insufficient for sovereign-grade financial infrastructure that handles:
+- Multi-sovereign operations
+- High-value transactions
+- Regulatory compliance requirements
+- Cross-border operations
+
+## Decision
+Implement a zero-trust authentication strategy using:
+1. **Sovereign Identity Tokens (SIT)**: JWT-based tokens with sovereign bank identity
+2. **Request Signature Verification**: HSM-backed cryptographic signatures for each request
+3. **Multi-layer Validation**: Token validation + signature verification + timestamp/nonce checks
+4. **HSM Integration**: Hardware Security Module for key management and signing
+
+## Consequences
+
+### Positive
+- Strong security with multiple validation layers
+- HSM-backed cryptographic operations
+- Replay attack prevention (timestamp/nonce)
+- Sovereign identity verification
+- Scalable across multiple sovereign banks
+
+### Negative
+- More complex implementation
+- Requires HSM infrastructure
+- Slightly higher latency per request
+- More complex client implementation
+
+### Risks
+- HSM availability dependency
+- Signature verification performance at scale
+- Key rotation complexity
+
+## Alternatives Considered
+
+1. **Simple JWT Only**: Basic JWT authentication
+   - Pros: Simple, fast
+   - Cons: Insufficient security for financial operations
+
+2. **API Keys**: Static API keys
+   - Pros: Very simple
+   - Cons: No cryptographic verification, weak security
+
+3. **Zero-Trust with HSM**: Chosen approach
+   - Pros: Strong security, regulatory compliance, sovereign-grade
+   - Cons: More complex
+
+## Implementation
+- JWT tokens with sovereign bank identity
+- Request signature headers (X-SOV-SIGNATURE, X-SOV-TIMESTAMP, X-SOV-NONCE)
+- HSM service integration for signature verification
+- Middleware: `zeroTrustAuthMiddleware` in `src/integration/api-gateway/middleware/auth.middleware.ts`
+
+## References
+- Zero Trust Architecture: https://www.nist.gov/publications/zero-trust-architecture
+- HSM Best Practices: https://www.nist.gov/publications/guidelines-selection-and-use-approval-cryptographic-modules
+

docs/adr/0005-settlement-architecture.md

@@ -0,0 +1,60 @@
+# ADR-0005: Multi-Layer Settlement Architecture
+
+## Status
+Accepted
+
+## Context
+The DBIS system requires settlement across multiple dimensions:
+- Multiple sovereign banks (33 SCBs)
+- Multiple asset types (fiat, CBDC, commodities, securities)
+- Multiple settlement modes (RTGS, atomic, T+1)
+- Cross-chain operations
+- Real-time and batch processing
+
+## Decision
+Implement a multi-layer settlement architecture:
+1. **Instant Settlement Network (ISN)**: Real-time atomic settlement
+2. **Global Settlement System (GSS)**: Four-layer architecture (Sovereign, DBIS Master, Smart Clearing, Finality)
+3. **Global Atomic Settlements (GAS) Network**: Multi-dimensional atomic settlement
+4. **Omega-Layer**: Final settlement layer for reality-spanning coherence
+5. **Cross-Chain Settlement**: Atomic swaps across different chains
+
+## Consequences
+
+### Positive
+- Supports multiple settlement modes
+- Atomic settlement guarantees
+- Cross-asset settlement capability
+- Scalable architecture
+- Finality and irreversibility
+
+### Negative
+- Complex architecture
+- Multiple systems to maintain
+- Potential for coordination overhead
+
+### Risks
+- Settlement failures across layers
+- Performance at scale
+- Complexity in debugging
+
+## Alternatives Considered
+
+1. **Single Settlement Layer**: One settlement system
+   - Pros: Simple
+   - Cons: Cannot handle all requirements
+
+2. **Multi-Layer Architecture**: Chosen approach
+   - Pros: Flexible, comprehensive, supports all use cases
+   - Cons: More complex
+
+## Implementation
+- ISN: `src/core/settlement/isn/`
+- GSS: `src/core/settlement/gss/`
+- GAS: `src/core/settlement/gas/`
+- Cross-Chain: `src/core/settlement/cross-chain/`
+
+## References
+- ISO 20022 Settlement Standards
+- Real-Time Gross Settlement (RTGS) Systems
+