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**:
```bash
# 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:

```bash
# 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)

```solidity
// 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

```solidity
// 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

```solidity
// 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

```solidity
// 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

```sql
-- 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.*