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

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