Initial commit

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/
+