Initial commit

docs/development.md

@@ -0,0 +1,208 @@
+# 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).
+