Goa-gel-fullstack/README.md

# Goa GEL - Government e-Licensing Platform

A blockchain-powered e-licensing platform for the Government of Goa, enabling transparent multi-department approval workflows with immutable audit trails.

## Features

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

## Tech Stack

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

## Quick Start

**Prerequisites**: Docker and Docker Compose

```bash
# Clone and start all services
git clone <repository-url>
cd Goa-GEL
docker-compose up -d
```

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

## Configuration

### Local Development

No configuration needed - just run `docker-compose up -d`.

### Remote Deployment (VM/Kubernetes)

Create a `.env` file from the template:

```bash
cp .env.example .env
```

Configure external access URLs:

```env
# Public URL where browsers access the API
API_BASE_URL=http://your-server-ip:3001/api/v1

# Frontend URL for CORS
CORS_ORIGIN=http://your-server-ip:4200
```

### Production

Update security credentials in `.env`:

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

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

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

## API Documentation

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

---

**Version**: 1.0.0
**Last Updated**: February 2026