Goa-gel-fullstack/docs/guides/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:

```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!*