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

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:

{
  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