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)

# 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

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