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
2026-02-07 10:23:29 -04:00
commit 80566bf0a2
441 changed files with 102418 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,225 @@
+# Goa GEL Blockchain Document Verification Platform - Architecture Diagrams
+
+## Overview
+This directory contains comprehensive architecture diagrams for the Goa Government E-License (GEL) Blockchain Document Verification Platform.
+
+## Diagrams
+
+### System Context Diagram
+- **File:** `system-context.mermaid`
+- **Type:** Mermaid Diagram
+
+### Container Architecture
+- **File:** `container-architecture.mermaid`
+- **Type:** Mermaid Diagram
+
+### Blockchain Architecture
+- **File:** `blockchain-architecture.mermaid`
+- **Type:** Mermaid Diagram
+
+### Workflow State Machine
+- **File:** `workflow-state-machine.mermaid`
+- **Type:** Mermaid Diagram
+
+### Data Flow Diagram
+- **File:** `data-flow.mermaid`
+- **Type:** Mermaid Diagram
+
+### 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
+```
+
+### 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
+```
+
+### 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
+
+## Diagram Contents
+
+### 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)
+
+### 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
+
+### 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
+
+### 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
+
+### 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
+
+### 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)
+
+Volumes & Configuration Files
+
+## Key Technical Decisions
+
+### 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
+
+### Tokens
+- **Standard:** ERC-721
+- **Type:** Soulbound NFTs
+- **Purpose:** Non-transferable license certificates
+- **Metadata:** Immutable license details
+
+### Backend
+- **Framework:** NestJS (TypeScript)
+- **Database:** PostgreSQL
+- **File Storage:** MinIO (S3-compatible)
+- **Cache:** Redis
+
+### 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
+```
+
+## Next Steps
+
+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
+
+---
+
+**Generated:** 2026-02-03
+**Platform:** Goa GEL Blockchain Document Verification
+**Version:** POC 1.0