feat: Goa GEL Blockchain e-Licensing Platform - Full Stack Implementation
Complete implementation of the Goa Government e-Licensing platform with: Backend: - NestJS API with JWT authentication - PostgreSQL database with Knex ORM - Redis caching and session management - MinIO document storage - Hyperledger Besu blockchain integration - Multi-department workflow system - Comprehensive API tests (266/282 passing) Frontend: - Angular 21 with standalone components - Angular Material + TailwindCSS UI - Visual workflow builder - Document upload with progress tracking - Blockchain explorer integration - Role-based dashboards (Admin, Department, Citizen) - E2E tests with Playwright (37 tests) Infrastructure: - Docker Compose orchestration - Blockscout blockchain explorer - Development and production configurations
This commit is contained in:
Mahi
535
docs/architecture/INDEX.md
Normal file
535
docs/architecture/INDEX.md
Normal file
@@ -0,0 +1,535 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user