Goa-gel-fullstack/backend/PROJECT_STRUCTURE.md

# 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