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/docs/guides/QUICK_START.md
+++ b/docs/guides/QUICK_START.md
@@ -0,0 +1,366 @@
+# Goa GEL - Quick Start Guide
+
+## 🚀 5-Minute Overview
+
+The **Goa Government E-License (GEL) Platform** is a blockchain-based document verification system that enables multi-department approval workflows for government licenses using:
+
+- **Hyperledger Besu** (blockchain)
+- **NestJS** (backend API)
+- **Next.js** (frontend)
+- **PostgreSQL** + **MinIO** (data storage)
+- **QBFT Consensus** (4 validators)
+- **ERC-721 Soulbound NFTs** (license certificates)
+
+---
+
+## 📂 What's in This Directory?
+
+```
+/sessions/cool-elegant-faraday/mnt/Goa-GEL/
+├── 6 Mermaid Diagrams (.mermaid files)
+├── 6 HTML Preview Files (.html files)
+├── 3 Documentation Files (.md files)
+└── 3 Utility Scripts (.js files)
+```
+
+---
+
+## 🎯 Start Here (Choose Your Role)
+
+### I'm a Project Manager / Non-Technical Stakeholder
+1. Open `system-context.html` in your browser
+2. Read `INDEX.md` - Section "Diagram Descriptions"
+3. Reference `ARCHITECTURE_GUIDE.md` - Sections 1, 7, 8
+
+**Time: 15 minutes**
+
+### I'm a Backend Developer
+1. Open `container-architecture.html`
+2. Read `ARCHITECTURE_GUIDE.md` - Sections 2, 3, 5, 6
+3. Study the smart contract details in Section 3
+4. Review data flow in Section 5
+
+**Time: 45 minutes**
+
+### I'm a Frontend Developer
+1. Open `system-context.html`
+2. Read `ARCHITECTURE_GUIDE.md` - Section 2 (Frontend Layer only)
+3. Review `container-architecture.html`
+4. Check deployment in Section 6
+
+**Time: 20 minutes**
+
+### I'm a DevOps / Infrastructure Engineer
+1. Open `deployment-architecture.html`
+2. Read `ARCHITECTURE_GUIDE.md` - Section 6 (Deployment)
+3. Review Docker Compose configuration details
+4. Check Section 3 for blockchain node setup
+
+**Time: 30 minutes**
+
+### I'm a Blockchain / Smart Contract Developer
+1. Open `blockchain-architecture.html`
+2. Read `ARCHITECTURE_GUIDE.md` - Section 3 (Blockchain Deep Dive)
+3. Study the 4 smart contracts section
+4. Review on-chain vs off-chain data split
+
+**Time: 40 minutes**
+
+### I'm a QA / Tester
+1. Open `workflow-state-machine.html`
+2. Open `data-flow.html`
+3. Read `ARCHITECTURE_GUIDE.md` - Sections 4 (Workflows) and 5 (Data Flow)
+4. Create test cases based on the 11-step process
+
+**Time: 35 minutes**
+
+---
+
+## 📊 View Diagrams
+
+### Browser Preview (Easiest)
+
+Open any .html file in your web browser:
+
+```bash
+# Linux/Mac
+firefox system-context.html
+
+# Or
+google-chrome container-architecture.html
+
+# Or (macOS)
+open workflow-state-machine.html
+```
+
+### Mermaid Live (Online, Interactive)
+
+1. Go to https://mermaid.live
+2. Copy content from any .mermaid file
+3. Paste into editor
+4. View instant diagram
+5. Download as PNG/SVG
+
+### Export to PNG (if needed)
+
+See `README.md` for 5 different methods:
+- **Method 1**: Mermaid Live (easiest)
+- **Method 2**: NPM CLI
+- **Method 3**: Docker
+- **Method 4**: Browser screenshot
+- **Method 5**: Kroki.io API
+
+---
+
+## 🏗️ Architecture at a Glance
+
+```
+┌─────────────────────────────────────────────────────┐
+│                  USERS / STAKEHOLDERS                │
+│  Citizens • Departments • Approvers • Admins         │
+└──────────────────┬──────────────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────────────┐
+│               FRONTEND (Next.js)                     │
+│         Port 3000 • shadcn/ui • Tailwind            │
+└──────────────────┬──────────────────────────────────┘
+                   │
+┌──────────────────▼──────────────────────────────────┐
+│          API GATEWAY (NestJS)                        │
+│    Port 3001 • Auth • Workflow • Approvals          │
+└──────────────────┬──────────────────────────────────┘
+                   │
+    ┌──────────────┼──────────────┬──────────────┐
+    │              │              │              │
+┌───▼────┐   ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
+│PostgreSQL  │  Redis  │   │  MinIO  │   │ Besu   │
+│(5432)   │  (6379)  │   │ (9000)  │   │(8545+) │
+│Database   │  Cache  │   │ Storage │   │Blockchain
+└──────────┘   └────────┘   └────────┘   └────────┘
+```
+
+**Key Components**:
+- Frontend: React UI for users
+- Backend: NestJS for business logic
+- Database: PostgreSQL for structured data
+- Cache: Redis for real-time state
+- Storage: MinIO for documents
+- Blockchain: Besu for immutable records
+
+---
+
+## 🔄 License Approval Flow (11 Steps)
+
+```
+1. Citizen Creates License Request
+   └─> Upload documents (PDF, images, etc.)
+
+2. Documents Hashed
+   └─> SHA-256 hash of each document
+
+3. Blockchain Recording
+   └─> Hash recorded on Besu (QBFT consensus)
+
+4. Route to Departments
+   └─> Tourism + Fire Safety (parallel)
+
+5-6. Departments Receive Notifications
+   └─> Ready for review
+
+7-8. Departments Approve (Parallel)
+   └─> Record approvals on blockchain
+
+9. NFT Minting
+   └─> ERC-721 Soulbound license certificate
+
+10. Notifications Sent
+   └─> Citizen receives approval
+
+11. Verification
+   └─> Anyone can verify on blockchain
+```
+
+---
+
+## ⛓️ Blockchain Details
+
+### Consensus
+- **Type**: QBFT (Quorum Byzantine Fault Tolerant)
+- **Validators**: 4 nodes
+- **Requirement**: 3/4 (75%) agreement
+- **Block Time**: ~12 seconds
+- **Network**: Private permissioned
+
+### Smart Contracts (4)
+
+| Contract | Purpose | Key Functions |
+|----------|---------|---|
+| LicenseRequestNFT | Issue licenses as NFTs | mint(), burn(), ownerOf() |
+| ApprovalManager | Record approvals | recordApproval(), getApprovalChain() |
+| DepartmentRegistry | Manage departments | registerDept(), setApprovers() |
+| WorkflowRegistry | Define workflows | defineWorkflow(), getWorkflow() |
+
+### Data Strategy
+
+**On-Chain** (Immutable & Verifiable):
+- License hashes
+- Approval signatures
+- Department registry
+- NFT ownership
+
+**Off-Chain** (Searchable & Scalable):
+- Full document details
+- Applicant information
+- Actual document files
+- Workflow state
+
+**Link**: SHA-256 hash bridges both worlds
+
+---
+
+## 🚀 Get Started
+
+### Step 1: View a Diagram
+```bash
+# Open system-context.html in your browser
+open /sessions/cool-elegant-faraday/mnt/Goa-GEL/system-context.html
+```
+
+### Step 2: Read Documentation
+- Start: `INDEX.md` (this is your navigation guide)
+- Quick overview: `README.md`
+- Deep dive: `ARCHITECTURE_GUIDE.md` (sections based on your role)
+
+### Step 3: Understand Your Domain
+- **Frontend Dev**: See container-architecture.html (Frontend section)
+- **Backend Dev**: See container-architecture.html (API section)
+- **Blockchain Dev**: See blockchain-architecture.html
+- **DevOps**: See deployment-architecture.html
+
+### Step 4: Plan Implementation
+Use the detailed architecture guide to plan your specific implementation.
+
+---
+
+## 📚 Documentation Files Explained
+
+| File | Best For | Read Time |
+|------|----------|-----------|
+| `INDEX.md` | Navigation & overview | 10 min |
+| `README.md` | Quick reference | 8 min |
+| `ARCHITECTURE_GUIDE.md` | Deep technical details | 30 min |
+| `QUICK_START.md` | This file - getting oriented | 5 min |
+
+---
+
+## 🎓 Learning Path (Recommended)
+
+### For Everyone (Required)
+1. ✓ Read this file (QUICK_START.md)
+2. ✓ Open system-context.html in browser
+3. ✓ Read INDEX.md
+
+**Time: 20 minutes**
+
+### Role-Specific (Choose One)
+**Backend Developers**:
+- container-architecture.html
+- ARCHITECTURE_GUIDE.md - Sections 2, 3, 5, 6
+- Database schema in Section 3
+
+**Frontend Developers**:
+- container-architecture.html (Frontend section)
+- deployment-architecture.html
+- ARCHITECTURE_GUIDE.md - Section 2
+
+**Blockchain Developers**:
+- blockchain-architecture.html
+- ARCHITECTURE_GUIDE.md - Section 3
+- Smart contracts overview
+
+**DevOps Engineers**:
+- deployment-architecture.html
+- ARCHITECTURE_GUIDE.md - Section 6
+- Docker Compose details
+
+---
+
+## ❓ Common Questions
+
+**Q: Where do I start?**
+A: Open `system-context.html` in your browser for a visual overview.
+
+**Q: How do I convert diagrams to PNG?**
+A: See `README.md` - 5 different methods listed (Mermaid Live is easiest).
+
+**Q: What's the technology stack?**
+A: See section "Technology Stack Summary" in INDEX.md or ARCHITECTURE_GUIDE.md appendix.
+
+**Q: How does blockchain integration work?**
+A: See data-flow.html (Steps 3, 9) and ARCHITECTURE_GUIDE.md Section 3.
+
+**Q: What's the deployment process?**
+A: See deployment-architecture.html and ARCHITECTURE_GUIDE.md Section 6.
+
+**Q: How many smart contracts are there?**
+A: 4 contracts: LicenseRequestNFT, ApprovalManager, DepartmentRegistry, WorkflowRegistry.
+
+**Q: Can I run this locally?**
+A: Yes, see deployment-architecture.html for Docker Compose setup.
+
+**Q: How does multi-department approval work?**
+A: See workflow-state-machine.html and data-flow.html (Steps 5-8).
+
+---
+
+## 📞 File Manifest
+
+```
+Core Diagrams (6 files):
+├── system-context.mermaid (40 lines)
+├── container-architecture.mermaid (64 lines)
+├── blockchain-architecture.mermaid (75 lines)
+├── workflow-state-machine.mermaid (65 lines)
+├── data-flow.mermaid (105 lines)
+└── deployment-architecture.mermaid (102 lines)
+
+HTML Previews (6 files):
+├── system-context.html
+├── container-architecture.html
+├── blockchain-architecture.html
+├── workflow-state-machine.html
+├── data-flow.html
+└── deployment-architecture.html
+
+Documentation (3 files):
+├── INDEX.md (comprehensive index and navigation)
+├── README.md (overview and PNG conversion)
+└── ARCHITECTURE_GUIDE.md (1000+ line technical guide)
+
+Utilities (3 files):
+├── convert.js
+├── convert-to-png.js
+└── screenshot-diagrams.js
+```
+
+**Total**: 18 files, 140 KB, 2,800+ lines of diagrams & docs
+
+---
+
+## ✅ Next Steps
+
+1. **Now**: Open any .html file in your browser
+2. **Next**: Read `INDEX.md` for detailed navigation
+3. **Then**: Read role-specific sections in `ARCHITECTURE_GUIDE.md`
+4. **Finally**: Use diagrams as reference during implementation
+
+---
+
+**Version**: 1.0
+**Created**: 2026-02-03
+**Platform**: Goa GEL (Government E-License)
+**Status**: POC Phase 1
+
+---
+
+*Ready to dive in? Open `system-context.html` now!*