docs: Update README with comprehensive platform documentation
This commit is contained in:
Mahi
383
README.md
383
README.md
@@ -1,225 +1,228 @@
|
|||||||
# Goa GEL Blockchain Document Verification Platform - Architecture Diagrams
|
# Goa GEL - Government e-Licensing Platform
|
||||||
|
|
||||||
## Overview
|
A blockchain-powered e-licensing platform for the Government of Goa, enabling transparent multi-department approval workflows with immutable audit trails.
|
||||||
This directory contains comprehensive architecture diagrams for the Goa Government E-License (GEL) Blockchain Document Verification Platform.
|
|
||||||
|
|
||||||
## Diagrams
|
## Features
|
||||||
|
|
||||||
### System Context Diagram
|
- **Multi-Department Workflows**: Sequential or parallel approval processes across government departments
|
||||||
- **File:** `system-context.mermaid`
|
- **Blockchain Integration**: Hyperledger Besu for immutable license records and NFT-based certificates
|
||||||
- **Type:** Mermaid Diagram
|
- **Document Management**: Secure document upload with hash verification and version history
|
||||||
|
- **Real-Time Tracking**: Citizens can track application status through the approval pipeline
|
||||||
|
- **Admin Dashboard**: Platform analytics, blockchain explorer, and department management
|
||||||
|
- **API Integration**: RESTful API with webhook support for external systems
|
||||||
|
|
||||||
### Container Architecture
|
## Tech Stack
|
||||||
- **File:** `container-architecture.mermaid`
|
|
||||||
- **Type:** Mermaid Diagram
|
|
||||||
|
|
||||||
### Blockchain Architecture
|
| Layer | Technology |
|
||||||
- **File:** `blockchain-architecture.mermaid`
|
|-------|------------|
|
||||||
- **Type:** Mermaid Diagram
|
| Frontend | Angular 17+, Angular Material, TailwindCSS |
|
||||||
|
| Backend | NestJS, TypeScript, Knex.js |
|
||||||
|
| Database | PostgreSQL 15 |
|
||||||
|
| Cache | Redis 7 |
|
||||||
|
| Storage | MinIO (S3-compatible) |
|
||||||
|
| Blockchain | Hyperledger Besu (QBFT consensus) |
|
||||||
|
| Explorer | Blockscout |
|
||||||
|
|
||||||
### Workflow State Machine
|
## Quick Start
|
||||||
- **File:** `workflow-state-machine.mermaid`
|
|
||||||
- **Type:** Mermaid Diagram
|
|
||||||
|
|
||||||
### Data Flow Diagram
|
**Prerequisites**: Docker and Docker Compose
|
||||||
- **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
|
```bash
|
||||||
# Install locally
|
# Clone and start all services
|
||||||
npm install --save-dev @mermaid-js/mermaid-cli
|
git clone <repository-url>
|
||||||
|
cd Goa-GEL
|
||||||
# Convert all files
|
docker-compose up -d
|
||||||
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
|
**Access Points**:
|
||||||
```bash
|
| Service | URL |
|
||||||
docker run --rm -v $(pwd):/data mermaid/mermaid-cli:latest \
|
|---------|-----|
|
||||||
-i /data/system-context.mermaid \
|
| Frontend | http://localhost:4200 |
|
||||||
-o /data/system-context.png \
|
| API | http://localhost:3001/api/v1 |
|
||||||
-t dark -b transparent
|
| Blockscout | http://localhost:4000 |
|
||||||
|
| MinIO Console | http://localhost:9001 |
|
||||||
|
|
||||||
|
**Default Test Users**:
|
||||||
|
| Role | Email | Password |
|
||||||
|
|------|-------|----------|
|
||||||
|
| Admin | admin@goagel.gov.in | Admin@123 |
|
||||||
|
| Tourism Dept | tourism.head@goa.gov.in | Tourism@123 |
|
||||||
|
| Citizen | citizen@example.com | Citizen@123 |
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Goa-GEL/
|
||||||
|
├── backend/ # NestJS API server
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── modules/ # Feature modules (auth, requests, workflows, etc.)
|
||||||
|
│ │ ├── database/ # Migrations, seeds, models
|
||||||
|
│ │ └── common/ # Shared utilities, guards, interceptors
|
||||||
|
│ └── scripts/ # Database and deployment scripts
|
||||||
|
├── frontend/ # Angular application
|
||||||
|
│ ├── src/app/
|
||||||
|
│ │ ├── features/ # Feature modules (dashboard, requests, approvals)
|
||||||
|
│ │ ├── core/ # Services, guards, interceptors
|
||||||
|
│ │ └── shared/ # Reusable components
|
||||||
|
│ └── e2e/ # Playwright tests
|
||||||
|
├── docs/ # Architecture documents
|
||||||
|
└── docker-compose.yml # Full platform orchestration
|
||||||
```
|
```
|
||||||
|
|
||||||
### Option 4: Browser Method
|
## Configuration
|
||||||
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
|
### Local Development
|
||||||
|
|
||||||
### 1. system-context.mermaid
|
No configuration needed - just run `docker-compose up -d`.
|
||||||
**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
|
### Remote Deployment (VM/Kubernetes)
|
||||||
**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
|
Create a `.env` file from the template:
|
||||||
**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
|
```bash
|
||||||
**License Request Workflow States**
|
cp .env.example .env
|
||||||
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
|
Configure external access URLs:
|
||||||
**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
|
```env
|
||||||
**Docker Compose Deployment**
|
# Public URL where browsers access the API
|
||||||
Services:
|
API_BASE_URL=http://your-server-ip:3001/api/v1
|
||||||
- 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
|
# Frontend URL for CORS
|
||||||
|
CORS_ORIGIN=http://your-server-ip:4200
|
||||||
|
```
|
||||||
|
|
||||||
## Key Technical Decisions
|
### Production
|
||||||
|
|
||||||
### Blockchain
|
Update security credentials in `.env`:
|
||||||
- **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
|
```env
|
||||||
- **Standard:** ERC-721
|
# Generate with: openssl rand -base64 32
|
||||||
- **Type:** Soulbound NFTs
|
JWT_SECRET=your-secure-jwt-secret-min-32-chars
|
||||||
- **Purpose:** Non-transferable license certificates
|
|
||||||
- **Metadata:** Immutable license details
|
# Strong passwords
|
||||||
|
DATABASE_PASSWORD=your-secure-db-password
|
||||||
|
MINIO_ACCESS_KEY=your-minio-access-key
|
||||||
|
MINIO_SECRET_KEY=your-minio-secret-key
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
### Backend
|
### Backend
|
||||||
- **Framework:** NestJS (TypeScript)
|
|
||||||
- **Database:** PostgreSQL
|
```bash
|
||||||
- **File Storage:** MinIO (S3-compatible)
|
cd backend
|
||||||
- **Cache:** Redis
|
npm install
|
||||||
|
npm run start:dev # Development with hot reload
|
||||||
|
npm run test # Run tests
|
||||||
|
npm run db:migrate # Run migrations
|
||||||
|
npm run db:seed # Seed database
|
||||||
|
```
|
||||||
|
|
||||||
### Frontend
|
### Frontend
|
||||||
- **Framework:** Next.js 14
|
|
||||||
- **UI:** shadcn/ui
|
|
||||||
- **State Management:** React Context/TanStack Query
|
|
||||||
- **Styling:** Tailwind CSS
|
|
||||||
|
|
||||||
### Authentication
|
```bash
|
||||||
- **POC Phase:** API Key + Secret
|
cd frontend
|
||||||
- **Future:** DigiLocker Integration (Mocked)
|
npm install
|
||||||
|
npm start # Development server at http://localhost:4200
|
||||||
## Architecture Benefits
|
npm run build # Production build
|
||||||
|
npm run test # Run unit tests
|
||||||
1. **Immutable Records**: Blockchain ensures license records cannot be tampered with
|
npm run e2e # Run Playwright tests
|
||||||
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
|
## API Documentation
|
||||||
|
|
||||||
1. Review all diagrams to understand system architecture
|
API endpoints follow RESTful conventions at `/api/v1`:
|
||||||
2. Use these for documentation and stakeholder presentations
|
|
||||||
3. Convert to PNG/SVG for inclusion in technical documentation
|
| Endpoint | Description |
|
||||||
4. Share with team for feedback and refinement
|
|----------|-------------|
|
||||||
|
| `/auth` | Authentication (login, register, refresh) |
|
||||||
|
| `/requests` | License applications CRUD |
|
||||||
|
| `/approvals` | Approval workflow actions |
|
||||||
|
| `/documents` | Document upload and management |
|
||||||
|
| `/workflows` | Workflow configuration |
|
||||||
|
| `/departments` | Department management |
|
||||||
|
| `/admin` | Platform administration |
|
||||||
|
|
||||||
|
Health check: `GET /api/v1/health`
|
||||||
|
|
||||||
|
## Blockchain
|
||||||
|
|
||||||
|
Smart contracts are automatically deployed on first startup:
|
||||||
|
|
||||||
|
- **LicenseNFT**: ERC-721 soulbound tokens for approved licenses
|
||||||
|
- **ApprovalManager**: Multi-signature approval tracking
|
||||||
|
- **DepartmentRegistry**: Department configuration on-chain
|
||||||
|
- **WorkflowRegistry**: Workflow definitions
|
||||||
|
|
||||||
|
Contract addresses are stored in `/app/.env` inside the API container.
|
||||||
|
|
||||||
|
## Services
|
||||||
|
|
||||||
|
| Service | Port | Description |
|
||||||
|
|---------|------|-------------|
|
||||||
|
| frontend | 4200 | Angular web application |
|
||||||
|
| api | 3001 | NestJS REST API |
|
||||||
|
| postgres | 5432 | Primary database |
|
||||||
|
| redis | 6379 | Cache and session store |
|
||||||
|
| minio | 9000/9001 | Document storage |
|
||||||
|
| besu-node-1 | 8545/8546 | Blockchain RPC |
|
||||||
|
| blockscout | 4000 | Blockchain explorer |
|
||||||
|
|
||||||
|
## Useful Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# View logs
|
||||||
|
docker-compose logs -f api
|
||||||
|
docker-compose logs -f frontend
|
||||||
|
|
||||||
|
# Restart a service
|
||||||
|
docker-compose restart api
|
||||||
|
|
||||||
|
# Reset database (WARNING: deletes all data)
|
||||||
|
docker-compose exec api npm run db:reset
|
||||||
|
|
||||||
|
# Access database
|
||||||
|
docker-compose exec postgres psql -U postgres -d goa_gel_platform
|
||||||
|
|
||||||
|
# Rebuild after code changes
|
||||||
|
docker-compose up -d --build api frontend
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||||
|
│ Citizen │ │ Department │ │ Admin │
|
||||||
|
│ Browser │ │ Operator │ │ Dashboard │
|
||||||
|
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
|
||||||
|
│ │ │
|
||||||
|
└───────────────────┼───────────────────┘
|
||||||
|
│
|
||||||
|
┌──────▼──────┐
|
||||||
|
│ Angular │
|
||||||
|
│ Frontend │
|
||||||
|
└──────┬──────┘
|
||||||
|
│
|
||||||
|
┌──────▼──────┐
|
||||||
|
│ NestJS │
|
||||||
|
│ API │
|
||||||
|
└──────┬──────┘
|
||||||
|
│
|
||||||
|
┌───────────────────┼───────────────────┐
|
||||||
|
│ │ │
|
||||||
|
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||||
|
│ PostgreSQL │ │ MinIO │ │ Hyperledger │
|
||||||
|
│ Database │ │ Storage │ │ Besu │
|
||||||
|
└─────────────┘ └─────────────┘ └─────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
Government of Goa - Internal Use
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Generated:** 2026-02-03
|
**Version**: 1.0.0
|
||||||
**Platform:** Goa GEL Blockchain Document Verification
|
**Last Updated**: February 2026
|
||||||
**Version:** POC 1.0
|
|
||||||
|
|||||||
Reference in New Issue
Block a user