Goa-gel-fullstack/docs/architecture/INDEX.md

Goa GEL Blockchain Document Verification Platform - Architecture Diagrams

Project Overview

This directory contains comprehensive C4 architecture diagrams and detailed technical documentation for the Goa Government E-License (GEL) Blockchain Document Verification Platform - a blockchain-based solution for managing multi-department approval workflows for government licenses and permits.

Status: POC Phase 1 Created: 2026-02-03 Platform: Hyperledger Besu + QBFT Consensus

---

Directory Contents

📋 Mermaid Diagram Files (.mermaid)

These files contain the raw diagram definitions in Mermaid syntax:

File	Description	C4 Level
system-context.mermaid	C4 Context diagram showing the GEL platform and all external actors/systems	Level 1
container-architecture.mermaid	C4 Container diagram detailing frontend, API, database, storage, and blockchain layers	Level 2
blockchain-architecture.mermaid	Detailed blockchain layer with 4 Besu validators, smart contracts, and on-chain/off-chain data split	Level 3
workflow-state-machine.mermaid	State machine showing license request and approval workflows	Business Logic
data-flow.mermaid	Complete 11-step end-to-end sequence diagram from license submission to verification	Sequence
deployment-architecture.mermaid	Docker Compose deployment topology with all services and networking	Infrastructure

Lines of Code: 451 total

🌐 HTML Preview Files (.html)

Browser-viewable versions of each diagram using CDN-hosted mermaid.js:

File	View In Browser
system-context.html	Open in browser for interactive viewing
container-architecture.html	Open in browser for interactive viewing
blockchain-architecture.html	Open in browser for interactive viewing
workflow-state-machine.html	Open in browser for interactive viewing
data-flow.html	Open in browser for interactive viewing
deployment-architecture.html	Open in browser for interactive viewing

Quick Start:

# On Linux/Mac
firefox system-context.html

# Or
google-chrome container-architecture.html

# Or just open in your default browser
open workflow-state-machine.html

📚 Documentation Files

File	Purpose	Size
ARCHITECTURE_GUIDE.md	Comprehensive 1000+ line technical guide covering all architectural aspects	28 KB
README.md	Quick reference guide with diagram descriptions and PNG conversion instructions	7 KB
INDEX.md	This file - directory guide and navigation

🛠️ Utility Scripts

File	Purpose
convert.js	Generate HTML preview files from mermaid definitions
convert-to-png.js	Provides PNG conversion instructions and guides
screenshot-diagrams.js	Kroki.io conversion attempts and multi-option guide

---

Quick Navigation

I want to...

Understand the system at a glance → Open system-context.html in your browser

See technical architecture details → Read ARCHITECTURE_GUIDE.md Section 2-3, or open container-architecture.html

Understand the blockchain layer → Read ARCHITECTURE_GUIDE.md Section 3, or open blockchain-architecture.html

Learn the approval workflow → Read ARCHITECTURE_GUIDE.md Section 4, or open workflow-state-machine.html

See the complete data flow → Read ARCHITECTURE_GUIDE.md Section 5 (11-step process), or open data-flow.html

Set up the development environment → Read ARCHITECTURE_GUIDE.md Section 6, or view deployment-architecture.html

Convert diagrams to PNG → Read README.md (Options 1-5), or run screenshot-diagrams.js

Get a technology overview → Read ARCHITECTURE_GUIDE.md Section 7 (Benefits), or Section 8 (Future)

---

Key Technical Specifications

Blockchain

• Platform: Hyperledger Besu
• Consensus: QBFT (Quorum Byzantine Fault Tolerant)
• Validators: 4 nodes (requires 3/4 approval)
• Block Time: ~12 seconds
• Network: Private Permissioned

Tokens

• Standard: ERC-721 Soulbound
• Type: Non-transferable license certificates
• Smart Contracts: 4 (LicenseRequestNFT, ApprovalManager, DepartmentRegistry, WorkflowRegistry)

Backend

• Framework: NestJS (TypeScript)
• Database: PostgreSQL
• Cache: Redis
• Storage: MinIO (S3-compatible)
• Port: 3001

Frontend

• Framework: Next.js 14
• UI Components: shadcn/ui
• Styling: Tailwind CSS
• Port: 3000

Authentication (POC)

• Method: API Key + Secret
• Future: DigiLocker Integration (mocked)

---

Diagram Descriptions

1. System Context Diagram

Level: C4 Context (Level 1) Type: Context Map Viewers: Non-technical stakeholders, Project managers

Shows the GEL platform as a black box with:

• External Actors: Citizens, Government Departments, Department Operators, Platform Operators
• External Systems: DigiLocker Mock, Legacy Department Systems, National Blockchain Federation
• Relationships: Information flows between actors and platform

Key Insights:

• Multi-stakeholder system with diverse user roles
• Integration with existing government infrastructure
• Future scalability through NBF integration

---

2. Container Architecture Diagram

Level: C4 Container (Level 2) Type: Architecture Diagram Viewers: Technical architects, DevOps engineers, Backend developers

Shows major system components:

• Frontend: Next.js 14 + shadcn/ui (Port 3000)
• API Gateway: NestJS with Auth, Workflow, Approval, Document services (Port 3001)
• Database: PostgreSQL for persistent storage (Port 5432)
• Cache: Redis for session and state management (Port 6379)
• Storage: MinIO for documents and certificates (Port 9000)
• Blockchain: Hyperledger Besu network (Port 8545+)

Key Insights:

• Layered architecture enables independent scaling
• Off-chain storage with on-chain hashing ensures efficiency
• Redis provides real-time state synchronization

---

3. Blockchain Architecture Diagram

Level: C4 Component (Level 3) Type: Detailed Technical Diagram Viewers: Blockchain developers, Smart contract engineers

Shows:

• 4 Validator Nodes: QBFT consensus topology
• Smart Contracts:
  • LicenseRequestNFT (ERC-721 Soulbound)
  • ApprovalManager (records approvals)
  • DepartmentRegistry (manages departments)
  • WorkflowRegistry (defines workflows)
• On-Chain Data: NFT state, approvals, registry info
• Off-Chain Data: Document details, applicant info, workflow state
• Data Linking: SHA-256 hashing creates immutable bridge

Key Insights:

• Hybrid on-chain/off-chain approach optimizes cost and performance
• QBFT requires 3/4 validator agreement for finality
• Hashing ensures off-chain data integrity

---

4. Workflow State Machine Diagram

Level: Business Logic Type: State Diagram Viewers: Business analysts, QA engineers, Product managers

Shows:

• Request States: DRAFT → SUBMITTED → IN_REVIEW → APPROVED/REJECTED/REVOKED
• Approval States: PENDING → APPROVED/REJECTED/CHANGES_REQUESTED
• Transitions: Rules for moving between states
• Terminal States: APPROVED, REJECTED (with paths for reapplication)

Key Insights:

• Supports iterative approval processes (PENDING_RESUBMISSION)
• Multi-department flexibility (parallel or sequential)
• Clear audit trail with state history

---

5. Data Flow Diagram

Level: Sequence Type: Sequence Diagram Viewers: Integration engineers, Backend developers, QA team

11-Step Process:

1. License Request Creation
2. Document Upload & Hashing
3. Blockchain Hash Recording
4. State Update to SUBMITTED
5. Route to Department 1 (parallel)
6. Route to Department 2 (parallel)
7. Department 1 Approval
8. Department 2 Approval (parallel)
9. Final Approval & NFT Minting
10. Notifications & State Update
11. License Verification

Key Insights:

• Parallel approvals reduce total approval time
• Immutable blockchain recording ensures accountability
• WebSocket notifications keep stakeholders informed
• Verification requires only blockchain query (decentralized)

---

6. Deployment Architecture Diagram

Level: Infrastructure Type: Deployment Diagram Viewers: DevOps engineers, System administrators, Infrastructure team

Shows:

• Docker Compose Setup: All services containerized
• Networking: gel-network bridge with defined subnets
• Volumes: Named volumes for persistent data
• Service Dependencies: Build order and healthchecks
• Monitoring: Prometheus & Grafana integration
• Port Mappings: All service ports clearly labeled

Key Insights:

• Single docker-compose file enables reproducible deployments
• Health checks ensure service reliability
• Monitoring integration enables production observability
• Volumes ensure data persistence across restarts

---

Viewing the Diagrams

Option 1: Browser Preview (Recommended for Quick Review)

Open any .html file in your web browser:

# Examples
firefox /sessions/cool-elegant-faraday/mnt/Goa-GEL/system-context.html
google-chrome /sessions/cool-elegant-faraday/mnt/Goa-GEL/container-architecture.html
open /sessions/cool-elegant-faraday/mnt/Goa-GEL/workflow-state-machine.html  # macOS

Benefits:

• No installation required
• Instant rendering
• Interactive viewing
• Works offline (after loading)

Option 2: Mermaid Live (Online, Interactive)

Visit https://mermaid.live and:

1. Click "Paste into editor"
2. Copy content from any .mermaid file
3. Instant visualization
4. Export as PNG, SVG, PDF

Option 3: Convert to PNG

See README.md for 5 different conversion methods:

1. Mermaid Live - Easiest, no installation
2. NPM CLI - Local installation
3. Docker - Containerized conversion
4. Browser DevTools - Manual screenshot
5. Kroki.io - Online API service

---

Smart Contract Details

LicenseRequestNFT (ERC-721 Soulbound)

// Non-transferable license certificates
// Functions: mint(), burn(), ownerOf(), tokenURI()
// Properties: Cannot be sold or transferred
// Use Case: Permanent license ownership record

Key Features:

• ERC-721 standard compliance
• Soulbound (non-transferable)
• Metadata stored in MinIO, URI on-chain
• Immutable once issued

ApprovalManager

// Records multi-department approvals
// Functions: recordApproval(), recordRejection(), requestChanges()
// Data: Complete approval chain with signatures
// Use Case: Transparent approval workflow

Key Features:

• Approval signatures prevent repudiation
• Full history queryable on-chain
• Reason tracking for rejections
• Change request details stored

DepartmentRegistry

// Manages department information
// Functions: registerDepartment(), setApprovers(), getApprovers()
// Use Case: Access control and authority verification

Key Features:

• Department metadata storage
• Approver list management
• Active/inactive status tracking

WorkflowRegistry

// Defines license approval workflows
// Functions: defineWorkflow(), getWorkflow(), getNextApprovers()
// Use Case: Flexible workflow configuration

Key Features:

• License-type specific workflows
• Sequential or parallel approval modes
• Timeout configurations
• Department ordering

---

Database Schema (PostgreSQL)

Key Tables

-- License Requests
license_requests (
  id, applicant_id, license_type, status,
  blockchain_tx_hash, blockchain_block_num,
  nft_token_id, created_at, submitted_at, approved_at
)

-- Multi-Department Approvals
approvals (
  id, license_id, department, status,
  reviewed_by, reviewed_at, comments, signature
)

-- Document Metadata
documents (
  id, license_id, filename, content_hash,
  file_size, file_type, uploaded_at, minio_path
)

-- Audit Logs
audit_logs (
  id, license_id, action, user_id,
  old_status, new_status, timestamp
)

-- Department Registry
departments (
  id, name, is_active, metadata,
  created_at, updated_at
)

---

File Locations

All files are located in:

/sessions/cool-elegant-faraday/mnt/Goa-GEL/

Complete File List

├── system-context.mermaid               (40 lines)
├── system-context.html                  (76 lines)
├── container-architecture.mermaid       (64 lines)
├── container-architecture.html          (100 lines)
├── blockchain-architecture.mermaid      (75 lines)
├── blockchain-architecture.html         (111 lines)
├── workflow-state-machine.mermaid       (65 lines)
├── workflow-state-machine.html          (101 lines)
├── data-flow.mermaid                    (105 lines)
├── data-flow.html                       (141 lines)
├── deployment-architecture.mermaid      (102 lines)
├── deployment-architecture.html         (138 lines)
├── convert.js                           (71 lines)
├── convert-to-png.js                    (235 lines)
├── screenshot-diagrams.js               (156 lines)
├── README.md                            (225 lines)
├── ARCHITECTURE_GUIDE.md                (1018 lines)
└── INDEX.md                             (this file)

Total: 2,823 lines of diagrams, code, and documentation

---

Getting Started

Step 1: View Diagrams

Open any .html file in your web browser to see the diagrams rendered.

Step 2: Read Documentation

Start with README.md for an overview, then read specific sections in ARCHITECTURE_GUIDE.md based on your role:

• Project Manager: Sections 1, 7, 8
• Backend Developer: Sections 2, 3, 5, 6
• Frontend Developer: Section 2 (Frontend Layer)
• DevOps Engineer: Sections 3 (Blockchain), 6 (Deployment)
• Blockchain Developer: Sections 3 (Smart Contracts)
• QA/Tester: Sections 4, 5 (Workflows)

Step 3: Understand the Flow

Review the data flow diagram (Section 5) to understand the complete end-to-end process.

Step 4: Plan Implementation

Use the deployment architecture (Section 6) and smart contract details (Section 3) to begin development.

---

Key Takeaways

Architecture Highlights

✓ Multi-layered design separates concerns and enables scaling ✓ Hybrid blockchain approach optimizes cost and performance ✓ Immutable records prevent tampering and ensure trust ✓ Parallel workflows reduce approval time ✓ Soulbound NFTs enable non-transferable license ownership ✓ Open standards (ERC-721, REST API) ensure interoperability

Technical Strengths

✓ QBFT Consensus ensures high finality (3/4 Byzantine fault tolerant) ✓ Off-chain storage with on-chain hashing optimizes costs ✓ Real-time caching via Redis reduces database load ✓ Docker Compose enables reproducible deployments ✓ Comprehensive audit trail supports compliance and investigations

Business Benefits

✓ Transparent verification builds citizen trust ✓ Multi-department coordination streamlines approvals ✓ Immutable certificates prevent fraud ✓ Future interoperability via blockchain standards ✓ Scalable architecture supports growth

---

Support & Questions

For questions about specific diagrams or architecture decisions:

1. System Context: See ARCHITECTURE_GUIDE.md Section 1
2. Container Architecture: See ARCHITECTURE_GUIDE.md Section 2
3. Blockchain Details: See ARCHITECTURE_GUIDE.md Section 3
4. Workflows: See ARCHITECTURE_GUIDE.md Section 4
5. Data Flow: See ARCHITECTURE_GUIDE.md Section 5
6. Deployment: See ARCHITECTURE_GUIDE.md Section 6
7. Conversion Help: See README.md (Options 1-5)

---

Appendix: Technology Stack Summary

Component	Technology	Version	Purpose
Blockchain	Hyperledger Besu	Latest	QBFT consensus, smart contracts
Consensus	QBFT	-	Byzantine fault tolerant agreement
Tokens	ERC-721 Soulbound	-	Non-transferable licenses
Backend	NestJS	TypeScript	REST API, business logic
Database	PostgreSQL	15+	Persistent data storage
Cache	Redis	7+	Session, state management
Storage	MinIO	Latest	S3-compatible file storage
Frontend	Next.js	14+	React-based UI
UI Components	shadcn/ui	Latest	Accessible components
Styling	Tailwind CSS	Latest	Utility-first CSS
DevOps	Docker Compose	Latest	Containerization, orchestration
Monitoring	Prometheus	Latest	Metrics collection
Visualization	Grafana	Latest	Dashboard creation

---

Document Version: 1.0 Created: 2026-02-03 Platform: Goa GEL (Government E-License) Phase: POC 1.0 Status: Complete Diagrams: 6 (C4 + Business Logic) Documentation: 1,243 lines Total Artifacts: 18 files

---

For the latest version of these diagrams, visit the source directory.