Goa-gel-fullstack/README.md

# 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