From cbcfa43d32e719a2bf1a9eb440a009ecae7dc2da Mon Sep 17 00:00:00 2001 From: Mahi Date: Sun, 8 Feb 2026 18:47:41 -0400 Subject: [PATCH] docs: Update README with comprehensive platform documentation --- README.md | 383 +++++++++++++++++++++++++++--------------------------- 1 file changed, 193 insertions(+), 190 deletions(-) diff --git a/README.md b/README.md index 699dd31..6a7e8d5 100644 --- a/README.md +++ b/README.md @@ -1,225 +1,228 @@ -# Goa GEL Blockchain Document Verification Platform - Architecture Diagrams +# Goa GEL - Government e-Licensing Platform -## Overview -This directory contains comprehensive architecture diagrams for the Goa Government E-License (GEL) Blockchain Document Verification Platform. +A blockchain-powered e-licensing platform for the Government of Goa, enabling transparent multi-department approval workflows with immutable audit trails. -## Diagrams +## Features -### System Context Diagram -- **File:** `system-context.mermaid` -- **Type:** Mermaid Diagram +- **Multi-Department Workflows**: Sequential or parallel approval processes across government departments +- **Blockchain Integration**: Hyperledger Besu for immutable license records and NFT-based certificates +- **Document Management**: Secure document upload with hash verification and version history +- **Real-Time Tracking**: Citizens can track application status through the approval pipeline +- **Admin Dashboard**: Platform analytics, blockchain explorer, and department management +- **API Integration**: RESTful API with webhook support for external systems -### Container Architecture -- **File:** `container-architecture.mermaid` -- **Type:** Mermaid Diagram +## Tech Stack -### Blockchain Architecture -- **File:** `blockchain-architecture.mermaid` -- **Type:** Mermaid Diagram +| Layer | Technology | +|-------|------------| +| Frontend | Angular 17+, Angular Material, TailwindCSS | +| Backend | NestJS, TypeScript, Knex.js | +| Database | PostgreSQL 15 | +| Cache | Redis 7 | +| Storage | MinIO (S3-compatible) | +| Blockchain | Hyperledger Besu (QBFT consensus) | +| Explorer | Blockscout | -### Workflow State Machine -- **File:** `workflow-state-machine.mermaid` -- **Type:** Mermaid Diagram +## Quick Start -### Data Flow Diagram -- **File:** `data-flow.mermaid` -- **Type:** Mermaid Diagram +**Prerequisites**: Docker and Docker Compose -### Deployment Architecture -- **File:** `deployment-architecture.mermaid` -- **Type:** Mermaid Diagram - - -## Converting Mermaid to PNG - -### Option 1: Online Converter -Visit https://mermaid.live and: -1. Click "Upload File" -2. Select each .mermaid file -3. Click the download icon to export as PNG - -### Option 2: Using Mermaid CLI (Local Installation) ```bash -# Install locally -npm install --save-dev @mermaid-js/mermaid-cli - -# Convert all files -npx mmdc -i system-context.mermaid -o system-context.png -t dark -b transparent -npx mmdc -i container-architecture.mermaid -o container-architecture.png -t dark -b transparent -npx mmdc -i blockchain-architecture.mermaid -o blockchain-architecture.png -t dark -b transparent -npx mmdc -i workflow-state-machine.mermaid -o workflow-state-machine.png -t dark -b transparent -npx mmdc -i data-flow.mermaid -o data-flow.png -t dark -b transparent -npx mmdc -i deployment-architecture.mermaid -o deployment-architecture.png -t dark -b transparent +# Clone and start all services +git clone +cd Goa-GEL +docker-compose up -d ``` -### Option 3: Using Docker -```bash -docker run --rm -v $(pwd):/data mermaid/mermaid-cli:latest \ - -i /data/system-context.mermaid \ - -o /data/system-context.png \ - -t dark -b transparent +**Access Points**: +| Service | URL | +|---------|-----| +| Frontend | http://localhost:4200 | +| API | http://localhost:3001/api/v1 | +| Blockscout | http://localhost:4000 | +| MinIO Console | http://localhost:9001 | + +**Default Test Users**: +| Role | Email | Password | +|------|-------|----------| +| Admin | admin@goagel.gov.in | Admin@123 | +| Tourism Dept | tourism.head@goa.gov.in | Tourism@123 | +| Citizen | citizen@example.com | Citizen@123 | + +## Project Structure + +``` +Goa-GEL/ +├── backend/ # NestJS API server +│ ├── src/ +│ │ ├── modules/ # Feature modules (auth, requests, workflows, etc.) +│ │ ├── database/ # Migrations, seeds, models +│ │ └── common/ # Shared utilities, guards, interceptors +│ └── scripts/ # Database and deployment scripts +├── frontend/ # Angular application +│ ├── src/app/ +│ │ ├── features/ # Feature modules (dashboard, requests, approvals) +│ │ ├── core/ # Services, guards, interceptors +│ │ └── shared/ # Reusable components +│ └── e2e/ # Playwright tests +├── docs/ # Architecture documents +└── docker-compose.yml # Full platform orchestration ``` -### Option 4: Browser Method -Open each .html file in a web browser and: -1. Press F12 to open DevTools -2. Use Chrome DevTools to capture the diagram as an image -3. Or use a screenshot tool +## Configuration -## Diagram Contents +### Local Development -### 1. system-context.mermaid -**C4 Level 1 Context Diagram** -- Shows the GEL platform as a black box -- External actors: Citizens, Government Departments, Department Operators, Platform Operators -- External systems: DigiLocker Mock, Legacy Department Systems, National Blockchain Federation (future) +No configuration needed - just run `docker-compose up -d`. -### 2. container-architecture.mermaid -**C4 Level 2 Container Diagram** -- Frontend: Next.js 14 with shadcn/ui (Port 3000) -- Backend: NestJS API Gateway (Port 3001) -- Database: PostgreSQL (Port 5432) -- Cache: Redis (Port 6379) -- Storage: MinIO S3-compatible (Port 9000) -- Blockchain: Hyperledger Besu nodes -- Services: Auth, Workflow, Approval, Document +### Remote Deployment (VM/Kubernetes) -### 3. blockchain-architecture.mermaid -**Blockchain Layer Deep Dive** -- 4 Hyperledger Besu Validator Nodes (QBFT Consensus) -- RPC Ports: 8545-8548 -- Smart Contracts: - - LicenseRequestNFT (ERC-721 Soulbound) - - ApprovalManager - - DepartmentRegistry - - WorkflowRegistry -- On-Chain vs Off-Chain Data Split -- Content Hashing (SHA-256) for Immutable Links +Create a `.env` file from the template: -### 4. workflow-state-machine.mermaid -**License Request Workflow States** -States: -- DRAFT: Initial local draft -- SUBMITTED: Hash recorded on blockchain -- IN_REVIEW: Multi-department approval -- PENDING_RESUBMISSION: Changes requested -- APPROVED: License granted, NFT minted -- REJECTED: Request denied -- REVOKED: License cancelled +```bash +cp .env.example .env +``` -### 5. data-flow.mermaid -**Complete End-to-End Sequence** -11-Step Process: -1. License Request Submission -2. Document Upload & Hashing -3. Blockchain Recording -4. State Update to SUBMITTED -5. Route to Department 1 (Tourism) -6. Route to Department 2 (Fire Safety) - Parallel -7. Department 1 Approval -8. Department 2 Approval - Parallel -9. Final Approval Processing -10. Update Final State & Notifications -11. License Verification +Configure external access URLs: -### 6. deployment-architecture.mermaid -**Docker Compose Deployment** -Services: -- Frontend: Next.js (Port 3000) -- Backend: NestJS (Port 3001) -- Database: PostgreSQL (Port 5432) -- Cache: Redis (Port 6379) -- Storage: MinIO (Port 9000, 9001) -- Blockchain: 4x Besu Validators (Ports 8545-8548) -- Monitoring: Prometheus (9090), Grafana (3000 alt) +```env +# Public URL where browsers access the API +API_BASE_URL=http://your-server-ip:3001/api/v1 -Volumes & Configuration Files +# Frontend URL for CORS +CORS_ORIGIN=http://your-server-ip:4200 +``` -## Key Technical Decisions +### Production -### Blockchain -- **Platform:** Hyperledger Besu -- **Consensus:** QBFT (Quorum Byzantine Fault Tolerant) -- **Network Type:** Private Permissioned -- **Validators:** 4 nodes (requires 3/4 approval) -- **Block Time:** ~12 seconds +Update security credentials in `.env`: -### Tokens -- **Standard:** ERC-721 -- **Type:** Soulbound NFTs -- **Purpose:** Non-transferable license certificates -- **Metadata:** Immutable license details +```env +# Generate with: openssl rand -base64 32 +JWT_SECRET=your-secure-jwt-secret-min-32-chars + +# Strong passwords +DATABASE_PASSWORD=your-secure-db-password +MINIO_ACCESS_KEY=your-minio-access-key +MINIO_SECRET_KEY=your-minio-secret-key +``` + +## Development ### Backend -- **Framework:** NestJS (TypeScript) -- **Database:** PostgreSQL -- **File Storage:** MinIO (S3-compatible) -- **Cache:** Redis + +```bash +cd backend +npm install +npm run start:dev # Development with hot reload +npm run test # Run tests +npm run db:migrate # Run migrations +npm run db:seed # Seed database +``` ### Frontend -- **Framework:** Next.js 14 -- **UI:** shadcn/ui -- **State Management:** React Context/TanStack Query -- **Styling:** Tailwind CSS -### Authentication -- **POC Phase:** API Key + Secret -- **Future:** DigiLocker Integration (Mocked) - -## Architecture Benefits - -1. **Immutable Records**: Blockchain ensures license records cannot be tampered with -2. **Multi-Department Workflows**: Parallel or sequential approvals based on license type -3. **Transparent Verification**: Anyone can verify license authenticity on blockchain -4. **Scalability**: Off-chain document storage with on-chain hashing -5. **Auditability**: Complete audit trail of all state changes -6. **Privacy**: Permissioned network with department access controls -7. **Future-Proof**: NFT standard enables future interoperability - -## Viewing Instructions - -1. **Mermaid Live** (Easiest): https://mermaid.live - - Copy-paste content from .mermaid files - - Instant preview and export - -2. **HTML Files** (Built-in Browser): - - Open system-context.html (and others) in any web browser - - Uses CDN-hosted mermaid.js for rendering - -3. **PNG Export**: - - Follow the conversion options above - - Recommended: Use mermaid-cli or online converter - -## File Listing - -``` -/sessions/cool-elegant-faraday/mnt/Goa-GEL/ -├── system-context.mermaid -├── system-context.html -├── container-architecture.mermaid -├── container-architecture.html -├── blockchain-architecture.mermaid -├── blockchain-architecture.html -├── workflow-state-machine.mermaid -├── workflow-state-machine.html -├── data-flow.mermaid -├── data-flow.html -├── deployment-architecture.mermaid -├── deployment-architecture.html -├── convert.js -├── convert-to-png.js -└── README.md +```bash +cd frontend +npm install +npm start # Development server at http://localhost:4200 +npm run build # Production build +npm run test # Run unit tests +npm run e2e # Run Playwright tests ``` -## Next Steps +## API Documentation -1. Review all diagrams to understand system architecture -2. Use these for documentation and stakeholder presentations -3. Convert to PNG/SVG for inclusion in technical documentation -4. Share with team for feedback and refinement +API endpoints follow RESTful conventions at `/api/v1`: + +| Endpoint | Description | +|----------|-------------| +| `/auth` | Authentication (login, register, refresh) | +| `/requests` | License applications CRUD | +| `/approvals` | Approval workflow actions | +| `/documents` | Document upload and management | +| `/workflows` | Workflow configuration | +| `/departments` | Department management | +| `/admin` | Platform administration | + +Health check: `GET /api/v1/health` + +## Blockchain + +Smart contracts are automatically deployed on first startup: + +- **LicenseNFT**: ERC-721 soulbound tokens for approved licenses +- **ApprovalManager**: Multi-signature approval tracking +- **DepartmentRegistry**: Department configuration on-chain +- **WorkflowRegistry**: Workflow definitions + +Contract addresses are stored in `/app/.env` inside the API container. + +## Services + +| Service | Port | Description | +|---------|------|-------------| +| frontend | 4200 | Angular web application | +| api | 3001 | NestJS REST API | +| postgres | 5432 | Primary database | +| redis | 6379 | Cache and session store | +| minio | 9000/9001 | Document storage | +| besu-node-1 | 8545/8546 | Blockchain RPC | +| blockscout | 4000 | Blockchain explorer | + +## Useful Commands + +```bash +# View logs +docker-compose logs -f api +docker-compose logs -f frontend + +# Restart a service +docker-compose restart api + +# Reset database (WARNING: deletes all data) +docker-compose exec api npm run db:reset + +# Access database +docker-compose exec postgres psql -U postgres -d goa_gel_platform + +# Rebuild after code changes +docker-compose up -d --build api frontend +``` + +## Architecture + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Citizen │ │ Department │ │ Admin │ +│ Browser │ │ Operator │ │ Dashboard │ +└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ + │ │ │ + └───────────────────┼───────────────────┘ + │ + ┌──────▼──────┐ + │ Angular │ + │ Frontend │ + └──────┬──────┘ + │ + ┌──────▼──────┐ + │ NestJS │ + │ API │ + └──────┬──────┘ + │ + ┌───────────────────┼───────────────────┐ + │ │ │ +┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ +│ PostgreSQL │ │ MinIO │ │ Hyperledger │ +│ Database │ │ Storage │ │ Besu │ +└─────────────┘ └─────────────┘ └─────────────┘ +``` + +## License + +Government of Goa - Internal Use --- -**Generated:** 2026-02-03 -**Platform:** Goa GEL Blockchain Document Verification -**Version:** POC 1.0 +**Version**: 1.0.0 +**Last Updated**: February 2026