dbis_core/docs/development.md

# Development Guide

This guide provides comprehensive instructions for setting up and developing the DBIS Core Banking System.

## Development Workflow

```mermaid
graph LR
    subgraph "Development Cycle"
        CLONE[Clone Repository]
        INSTALL[Install Dependencies]
        SETUP[Setup Environment]
        DEV[Develop Features]
        TEST[Run Tests]
        LINT[Lint & Format]
        COMMIT[Commit Changes]
    end
    
    CLONE --> INSTALL
    INSTALL --> SETUP
    SETUP --> DEV
    DEV --> TEST
    TEST --> LINT
    LINT --> COMMIT
    COMMIT --> DEV
```

## Local Setup

### Prerequisites

- Node.js 20.x or higher
- PostgreSQL 15.x or higher
- npm or yarn

### Installation

1. Clone the repository
2. Install dependencies:
   ```bash
   npm install
   ```

3. Set up environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. Set up the database:
   ```bash
   npx prisma generate
   npx prisma migrate dev
   ```

5. Start the development server:
   ```bash
   npm run dev
   ```

## Testing

### Running Tests

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Test Structure

- Unit tests: `src/__tests__/unit/`
- Integration tests: `src/__tests__/integration/`
- E2E tests: `src/__tests__/e2e/`
- Test utilities: `src/__tests__/utils/`

### Writing Tests

1. Use the test utilities provided in `src/__tests__/utils/`
2. Follow the existing test patterns
3. Aim for 80%+ coverage for financial operations
4. Use descriptive test names

## Code Quality

### Linting

```bash
npm run lint
```

### Formatting

```bash
npm run format
```

### Type Checking

```bash
npx tsc --noEmit
```

## Code Contribution Guidelines

1. Follow TypeScript best practices
2. Use the shared utilities for common operations
3. Replace all `console.*` calls with the logger
4. Use the singleton Prisma client from `@/shared/database/prisma`
5. Add tests for new features
6. Update documentation as needed

## Troubleshooting

### Database Connection Issues

- Verify `DATABASE_URL` in `.env`
- Check PostgreSQL is running
- Verify database exists

### Environment Variable Errors

- Run the application to see validation errors
- Check `.env.example` for required variables
- Ensure all required variables are set

### Test Failures

- Ensure test database is set up
- Check `TEST_DATABASE_URL` in environment
- Verify Prisma client is generated

## Development Best Practices

### Code Organization

```mermaid
graph TD
    subgraph "Development Practices"
        STRUCTURE[Follow Directory Structure]
        PATTERNS[Use Design Patterns]
        UTILS[Use Shared Utilities]
        TYPES[Type Safety]
    end
    
    STRUCTURE --> QUALITY[Code Quality]
    PATTERNS --> QUALITY
    UTILS --> QUALITY
    TYPES --> QUALITY
```

### Development Recommendations

**Priority: High**

1. **Use Shared Utilities**
   - **Description**: Use shared utilities for common operations
   - **Implementation**: 
     - Use `@/shared/utils/date-helpers` for date operations
     - Use `@/shared/utils/decimal-helpers` for decimal calculations
     - Use `@/shared/utils/validation-helpers` for validation
   - **Impact**: Ensures consistency and reduces code duplication
   - **Dependencies**: Shared utilities available

2. **Database Client Management**
   - **Description**: Always use singleton Prisma client
   - **Implementation**: 
     - Import from `@/shared/database/prisma`
     - Never create new PrismaClient instances
     - Use connection pooling
   - **Impact**: Prevents connection pool exhaustion
   - **Dependencies**: Singleton Prisma client configured

3. **Logging Standards**
   - **Description**: Use Winston logger instead of console
   - **Implementation**: 
     - Import logger from `@/infrastructure/monitoring/logger`
     - Use appropriate log levels
     - Include correlation IDs
   - **Impact**: Enables proper log aggregation and analysis
   - **Dependencies**: Winston logger configured

4. **Error Handling**
   - **Description**: Use custom error classes and proper error handling
   - **Implementation**: 
     - Use error helpers from `@/shared/utils/error-helpers`
     - Provide meaningful error messages
     - Log errors with context
   - **Impact**: Improves debugging and error tracking
   - **Dependencies**: Error helpers available

5. **Testing Coverage**
   - **Description**: Maintain high test coverage
   - **Implementation**: 
     - Aim for 80%+ coverage for financial operations
     - Write unit tests for all services
     - Add integration tests for API endpoints
   - **Impact**: Reduces bugs and improves code quality
   - **Dependencies**: Test framework configured

For more detailed best practices, see [BEST_PRACTICES.md](./BEST_PRACTICES.md).