mahi/Goa-gel-fullstack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update README with comprehensive platform documentation

Browse Source
This commit is contained in:
Mahi
2026-02-08 18:47:41 -04:00
parent d9de183e51
commit cbcfa43d32
1 changed files with 193 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files

383
README.md
View File

@@ -1,225 +1,228 @@
# Goa GEL Blockchain Document Verification Platform - Architecture Diagrams
# Goa GEL - Government e-Licensing Platform
## Overview
This directory contains comprehensive architecture diagrams for the Goa Government E-License (GEL) Blockchain Document Verification Platform.
A blockchain-powered e-licensing platform for the Government of Goa, enabling transparent multi-department approval workflows with immutable audit trails.
## Diagrams
## Features
### System Context Diagram
- **File:** `system-context.mermaid`
- **Type:** Mermaid Diagram
- **Multi-Department Workflows**: Sequential or parallel approval processes across government departments
- **Blockchain Integration**: Hyperledger Besu for immutable license records and NFT-based certificates
- **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
- **File:** `container-architecture.mermaid`
- **Type:** Mermaid Diagram
## Tech Stack
### Blockchain Architecture
- **File:** `blockchain-architecture.mermaid`
- **Type:** Mermaid Diagram
| Layer | Technology |
|-------|------------|
| 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
- **File:** `workflow-state-machine.mermaid`
- **Type:** Mermaid Diagram
## Quick Start
### Data Flow Diagram
- **File:** `data-flow.mermaid`
- **Type:** Mermaid Diagram
**Prerequisites**: Docker and Docker Compose
### 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
# 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
# Clone and start all services
git clone <repository-url>
cd Goa-GEL
docker-compose up -d
```
### Option 3: Using Docker
```bash
docker run --rm -v $(pwd):/data mermaid/mermaid-cli:latest \
-i /data/system-context.mermaid \
-o /data/system-context.png \
-t dark -b transparent
**Access Points**:
| Service | URL |
|---------|-----|
| Frontend | http://localhost:4200 |
| API | http://localhost:3001/api/v1 |
| 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
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
## Configuration
## Diagram Contents
### Local Development
### 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)
No configuration needed - just run `docker-compose up -d`.
### 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
### Remote Deployment (VM/Kubernetes)
### 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
Create a `.env` file from the template:
### 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
```bash
cp .env.example .env
```
### 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
Configure external access URLs:
### 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)
```env
# Public URL where browsers access the API
API_BASE_URL=http://your-server-ip:3001/api/v1
Volumes & Configuration Files
# Frontend URL for CORS
CORS_ORIGIN=http://your-server-ip:4200
```
## Key Technical Decisions
### Production
### 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
Update security credentials in `.env`:
### Tokens
- **Standard:** ERC-721
- **Type:** Soulbound NFTs
- **Purpose:** Non-transferable license certificates
- **Metadata:** Immutable license details
```env
# Generate with: openssl rand -base64 32
JWT_SECRET=your-secure-jwt-secret-min-32-chars
# Strong passwords
DATABASE_PASSWORD=your-secure-db-password
MINIO_ACCESS_KEY=your-minio-access-key
MINIO_SECRET_KEY=your-minio-secret-key
```
## Development
### Backend
- **Framework:** NestJS (TypeScript)
- **Database:** PostgreSQL
- **File Storage:** MinIO (S3-compatible)
- **Cache:** Redis
```bash
cd backend
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
- **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
```bash
cd frontend
npm install
npm start # Development server at http://localhost:4200
npm run build # Production build
npm run test # Run unit tests
npm run e2e # Run Playwright tests
```
## Next Steps
## API Documentation
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
API endpoints follow RESTful conventions at `/api/v1`:
| Endpoint | Description |
|----------|-------------|
| `/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
**Platform:** Goa GEL Blockchain Document Verification
**Version:** POC 1.0
**Version**: 1.0.0
**Last Updated**: February 2026