feat: Goa GEL Blockchain e-Licensing Platform - Full Stack Implementation
Complete implementation of the Goa Government e-Licensing platform with: Backend: - NestJS API with JWT authentication - PostgreSQL database with Knex ORM - Redis caching and session management - MinIO document storage - Hyperledger Besu blockchain integration - Multi-department workflow system - Comprehensive API tests (266/282 passing) Frontend: - Angular 21 with standalone components - Angular Material + TailwindCSS UI - Visual workflow builder - Document upload with progress tracking - Blockchain explorer integration - Role-based dashboards (Admin, Department, Citizen) - E2E tests with Playwright (37 tests) Infrastructure: - Docker Compose orchestration - Blockscout blockchain explorer - Development and production configurations
This commit is contained in:
Mahi
453
backend/PROJECT_STRUCTURE.md
Normal file
453
backend/PROJECT_STRUCTURE.md
Normal file
@@ -0,0 +1,453 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user