# Goa GEL Backend - Complete Project Structure ## Project Layout ``` /sessions/cool-elegant-faraday/mnt/Goa-GEL/backend/ ├── src/ │ ├── config/ │ │ ├── app.config.ts # Application configuration │ │ ├── database.config.ts # PostgreSQL TypeORM setup │ │ ├── blockchain.config.ts # Hyperledger Besu/Web3 setup │ │ ├── redis.config.ts # Redis client configuration │ │ ├── minio.config.ts # MinIO object storage setup │ │ └── jwt.config.ts # JWT authentication config │ │ │ ├── common/ │ │ ├── decorators/ │ │ │ ├── api-key.decorator.ts # API key authentication decorator │ │ │ ├── current-user.decorator.ts # Inject current user into request │ │ │ └── department.decorator.ts # Department requirement decorator │ │ │ │ │ ├── filters/ │ │ │ ├── http-exception.filter.ts # HTTP exception handler │ │ │ └── all-exceptions.filter.ts # Global exception handler │ │ │ │ │ ├── guards/ │ │ │ ├── jwt-auth.guard.ts # JWT authentication guard │ │ │ ├── api-key.guard.ts # API key authentication guard │ │ │ └── roles.guard.ts # Role-based access control guard │ │ │ │ │ ├── interceptors/ │ │ │ ├── logging.interceptor.ts # Request/response logging │ │ │ ├── transform.interceptor.ts # Response transformation │ │ │ └── timeout.interceptor.ts # Request timeout handling │ │ │ │ │ ├── pipes/ │ │ │ └── validation.pipe.ts # Custom validation pipe │ │ │ │ │ ├── utils/ │ │ │ ├── hash.util.ts # Password and data hashing (bcrypt, SHA256/512) │ │ │ ├── crypto.util.ts # Encryption/decryption (AES-256-GCM) │ │ │ └── date.util.ts # Date manipulation utilities │ │ │ │ │ ├── interfaces/ │ │ │ └── request-context.interface.ts # API response and pagination types │ │ │ │ │ └── constants/ │ │ ├── error-codes.ts # Error codes and messages │ │ └── events.ts # Application events │ │ │ ├── database/ │ │ ├── data-source.ts # TypeORM data source │ │ ├── migrations/ # TypeORM database migrations │ │ ├── seeders/ │ │ │ └── seed.ts # Database seeding script │ │ └── subscribers/ # TypeORM entity subscribers │ │ │ ├── blockchain/ │ │ ├── blockchain.service.ts # Blockchain service │ │ └── blockchain.module.ts # Blockchain module │ │ │ ├── storage/ │ │ ├── storage.service.ts # MinIO storage service │ │ └── storage.module.ts # Storage module │ │ │ ├── queue/ │ │ └── queue.module.ts # Bull queue configuration │ │ │ ├── modules/ # Feature modules (to be implemented) │ │ ├── auth/ │ │ ├── users/ │ │ ├── documents/ │ │ └── departments/ │ │ │ └── app.module.ts # Root module │ └── main.ts # Application entry point │ ├── test/ │ └── jest-e2e.json # E2E testing configuration │ ├── Configuration Files ├── .eslintrc.js # ESLint configuration (strict TypeScript rules) ├── .prettierrc # Code formatting rules ├── tsconfig.json # TypeScript strict configuration ├── nest-cli.json # NestJS CLI configuration ├── jest.config.js # Unit testing configuration ├── package.json # Dependencies and scripts │ ├── Docker & Deployment ├── Dockerfile # Multi-stage Docker build ├── docker-compose.yml # Development services (PostgreSQL, Redis, MinIO) │ ├── Environment & Git ├── .env.example # Environment variables template ├── .gitignore # Git ignore rules ├── .dockerignore # Docker ignore rules ├── .editorconfig # Editor configuration │ └── Documentation ├── README.md # Project documentation └── PROJECT_STRUCTURE.md # This file ``` ## File Descriptions ### Configuration (src/config/) 1. **app.config.ts** - Application name, version, port, host - API prefix configuration - CORS settings - File upload limits - Feature flags 2. **database.config.ts** - PostgreSQL connection settings - TypeORM configuration - Entity and migration paths - Logging and synchronization options 3. **blockchain.config.ts** - Hyperledger Besu RPC URL - Smart contract address - Gas price and limit settings - Private key for transactions - Network configuration 4. **redis.config.ts** - Redis host, port, password - Database selection - Retry and reconnection strategies - TLS/SSL options 5. **minio.config.ts** - MinIO endpoint and credentials - Bucket names for documents and archives - Region settings - SSL configuration 6. **jwt.config.ts** - JWT secret and expiration - Refresh token settings - API key header and value - Token validation ### Common Utilities (src/common/) 1. **Decorators** - `@ApiKeyAuth()`: Mark endpoints requiring API key - `@CurrentUser()`: Inject authenticated user - `@RequireDepartment()`: Enforce department access 2. **Filters** - `HttpExceptionFilter`: Handle HTTP exceptions consistently - `AllExceptionsFilter`: Catch unhandled exceptions 3. **Guards** - `JwtAuthGuard`: Validate JWT tokens - `ApiKeyGuard`: Validate API keys - `RolesGuard`: Enforce role-based access control 4. **Interceptors** - `LoggingInterceptor`: Log all HTTP requests/responses - `TransformInterceptor`: Standardize API responses - `TimeoutInterceptor`: Enforce request timeouts 5. **Pipes** - `ValidationPipe`: Validate and transform DTOs 6. **Utils** - `HashUtil`: Password hashing (bcrypt), file hashing (SHA256) - `CryptoUtil`: AES-256-GCM encryption/decryption - `DateUtil`: Date manipulation and formatting ### Database (src/database/) - **data-source.ts**: TypeORM DataSource configuration for CLI and programmatic access - **migrations/**: Version-controlled database schema changes - **seeders/**: Initial data population scripts - **subscribers/**: Entity lifecycle event handlers ### Core Services 1. **BlockchainService** (src/blockchain/) - Connect to Hyperledger Besu - Deploy and interact with smart contracts - Monitor transaction status - Handle blockchain errors 2. **StorageService** (src/storage/) - MinIO client initialization - Bucket creation and management - File upload/download operations - Secure file storage 3. **QueueModule** (src/queue/) - Bull queue configuration - Job queues: - document-verification - blockchain-transactions - document-archive - email-notifications - audit-logs ## Key Technologies ### Backend Framework - **NestJS 10**: Progressive Node.js framework - **TypeScript 5**: Strict typing, no `any` types ### Database - **PostgreSQL 16**: Relational database - **TypeORM 0.3**: ORM with migrations - **Redis 7**: Caching and sessions ### Blockchain - **Hyperledger Besu**: Ethereum-compatible blockchain - **ethers.js 6.9**: Web3 interaction library ### Storage - **MinIO 7**: S3-compatible object storage - **Multer**: File upload middleware ### Queue & Async - **Bull 4**: Redis-based job queue - **RxJS 7**: Reactive programming ### Authentication - **JWT**: Stateless authentication - **Passport.js**: Authentication middleware - **bcrypt**: Password hashing ### Monitoring & Logging - **Winston 3**: Structured logging - **Helmet 7**: Security headers - **Swagger/OpenAPI**: API documentation ### Testing - **Jest 29**: Unit testing - **Supertest 6**: HTTP testing - **ts-jest**: TypeScript support ### Code Quality - **ESLint 8**: Linting (strict rules) - **Prettier 3**: Code formatting - **Class-validator**: DTO validation - **Class-transformer**: Object transformation ## NPM Scripts ```bash npm run build # Build production bundle npm run start # Run production build npm run start:dev # Run with hot reload npm run start:debug # Run in debug mode npm run lint # Check and fix code style npm run format # Format code with Prettier npm run test # Run unit tests npm run test:watch # Watch and rerun tests npm run test:cov # Generate coverage report npm run test:e2e # Run end-to-end tests npm run migration:generate # Create new migration npm run migration:run # Run pending migrations npm run migration:revert # Revert last migration npm run seed # Seed database with initial data ``` ## Environment Variables ### Core - `NODE_ENV`: development | production - `APP_NAME`, `APP_VERSION`, `APP_PORT`, `APP_HOST` - `API_PREFIX`: API route prefix (default: /api/v1) ### Database - `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME` - `DATABASE_USER`, `DATABASE_PASSWORD` - `DATABASE_SSL`, `DATABASE_LOGGING`, `DATABASE_SYNCHRONIZE` ### Redis - `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_DB` - `REDIS_TLS`: Enable TLS ### Blockchain - `BLOCKCHAIN_RPC_URL`: Besu node RPC URL - `BLOCKCHAIN_CHAIN_ID`: Network chain ID - `BLOCKCHAIN_CONTRACT_ADDRESS`: Smart contract address - `BLOCKCHAIN_PRIVATE_KEY`: Account private key - `BLOCKCHAIN_GAS_PRICE`, `BLOCKCHAIN_GAS_LIMIT` ### MinIO - `MINIO_ENDPOINT`, `MINIO_PORT` - `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY` - `MINIO_BUCKET_DOCUMENTS`, `MINIO_BUCKET_ARCHIVES` ### Security - `JWT_SECRET`: JWT signing key (required) - `JWT_EXPIRATION`: Token lifetime (default: 7d) - `API_KEY_HEADER`, `API_KEY_VALUE`: API key authentication ### CORS & Throttling - `CORS_ORIGIN`: Allowed origins (comma-separated) - `CORS_CREDENTIALS`: Enable credentials - `THROTTLE_TTL`, `THROTTLE_LIMIT`: Rate limiting ### Features - `ENABLE_BLOCKCHAIN_VERIFICATION`: true | false - `ENABLE_AUDIT_LOGGING`: true | false - `ENABLE_EMAIL_NOTIFICATIONS`: true | false - `ENABLE_RATE_LIMITING`: true | false ## Module Responsibilities ### AppModule (Root) - Configures all application modules - Sets up database connection - Initializes Redis and queues - Configures throttling and validation ### BlockchainModule - Provides blockchain service - Manages Besu connections - Handles smart contract interactions ### StorageModule - Provides MinIO client - Manages object storage - Handles file operations ### QueueModule - Configures Bull queues - Manages async job processing - Handles background tasks ### Feature Modules (TBD) - **AuthModule**: Authentication and authorization - **UsersModule**: User management - **DocumentsModule**: Document operations - **DepartmentsModule**: Department management - **AuditModule**: Audit logging ## Error Handling All errors follow a standardized format: ```typescript { success: false, statusCode: number, message: string, error: { code: string, // e.g., "DOC_001" message: string, details?: object }, timestamp: string, // ISO 8601 path: string, requestId?: string } ``` Error codes are prefixed by domain: - `AUTH_*`: Authentication errors - `USER_*`: User management - `DOC_*`: Document operations - `CHAIN_*`: Blockchain operations - `STOR_*`: Storage operations - `VAL_*`: Validation errors - `DB_*`: Database errors - `QUEUE_*`: Queue operations ## Security Features 1. **Authentication** - JWT tokens with expiration - API key support - Passport.js integration 2. **Authorization** - Role-based access control (RBAC) - Department-based filtering - Permission validation 3. **Data Protection** - Password hashing (bcrypt, 12 rounds) - AES-256-GCM encryption - SSL/TLS support - HTTPS enforcement ready 4. **API Security** - Helmet security headers - CORS configuration - Rate limiting - Input validation - SQL injection prevention (TypeORM) 5. **Logging & Audit** - Request/response logging - Audit trail - Error tracking - Performance monitoring ## Testing Structure ``` test/ ├── jest-e2e.json # E2E configuration ├── e2e/ # E2E test files └── unit/ # Unit test files src/**/*.spec.ts # Unit test files (co-located) ``` ## Docker & Deployment ### Services in docker-compose.yml 1. **PostgreSQL 16**: Port 5432 2. **Redis 7**: Port 6379 3. **MinIO**: Ports 9000 (API), 9001 (Console) ### Production Build 1. Multi-stage Dockerfile for optimized image 2. Separate dev and production dependencies 3. Health checks configured ## Next Steps 1. Implement feature modules: - Authentication module - User management - Document management - Department management 2. Create database entities and migrations 3. Implement API endpoints 4. Add comprehensive tests 5. Configure blockchain integration 6. Set up CI/CD pipeline 7. Deploy to production infrastructure --- **Version**: 1.0.0 **Last Updated**: 2024-01-01 **Maintainer**: Government of Goa