Goa-gel-fullstack/Documentation/docs/QUICK_START.md

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:

# 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

# 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!