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 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