dbis_core/docs/development.md

Development Guide

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

Development Workflow

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:

   npm install
   

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

4. Set up the database:

   npx prisma generate
   npx prisma migrate dev
   

5. Start the development server:

   npm run dev
   

Testing

Running Tests

# 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

npm run lint

Formatting

npm run format

Type Checking

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

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.