# Goa GEL Database Schema

This directory contains all database entities, migrations, and seeders for the Goa GEL Blockchain Document Verification Platform.

## Directory Structure

```
src/database/
├── entities/              # TypeORM entity definitions
│   ├── applicant.entity.ts
│   ├── department.entity.ts
│   ├── license-request.entity.ts
│   ├── document.entity.ts
│   ├── document-version.entity.ts
│   ├── approval.entity.ts
│   ├── workflow.entity.ts
│   ├── workflow-state.entity.ts
│   ├── webhook.entity.ts
│   ├── webhook-log.entity.ts
│   ├── audit-log.entity.ts
│   ├── blockchain-transaction.entity.ts
│   └── index.ts
├── migrations/            # TypeORM migrations
│   └── 1704067200000-InitialSchema.ts
├── seeders/              # Database seeders
│   └── seed.ts
├── data-source.ts        # TypeORM DataSource configuration
└── index.ts              # Main exports
```

## Database Entities Overview

### Core Entities

1. **Applicant** - Represents individuals applying for licenses
   - Unique: digilockerId, email, walletAddress
   - Relations: OneToMany with LicenseRequest

2. **Department** - Represents government departments handling approvals
   - Unique: code, walletAddress
   - Relations: OneToMany with Approval, OneToMany with Webhook

3. **Workflow** - Defines multi-stage approval workflows
   - Unique: workflowType
   - Contains: stages, rules, and requirements
   - Relations: OneToMany with LicenseRequest

4. **LicenseRequest** - Main entity for license applications
   - Unique: requestNumber
   - Status: DRAFT, SUBMITTED, IN_REVIEW, PENDING_RESUBMISSION, APPROVED, REJECTED, REVOKED, CANCELLED
   - Relations: ManyToOne Applicant, ManyToOne Workflow, OneToMany Document, OneToMany Approval, OneToOne WorkflowState

### Document Management

5. **Document** - Represents uploaded documents for a request
   - Tracks: filename, version, hash, minio bucket location
   - Relations: ManyToOne LicenseRequest, OneToMany DocumentVersion

6. **DocumentVersion** - Audit trail for document changes
   - Tracks: version number, hash, file size, mime type, uploader
   - Ensures: (documentId, version) uniqueness

### Approval & Workflow

7. **Approval** - Records department approvals
   - Status: PENDING, APPROVED, REJECTED, CHANGES_REQUESTED, REVIEW_REQUIRED
   - Tracks: remarks, reviewed documents, blockchain tx hash
   - Can be invalidated with reason

8. **WorkflowState** - Tracks execution state of workflow
   - Current stage, completed stages, pending approvals
   - Full execution log with timestamps and details
   - OneToOne relationship with LicenseRequest

### Webhooks & Audit

9. **Webhook** - Department webhook configurations
   - Stores: URL, events to listen for, secret hash
   - Relations: OneToMany with WebhookLog

10. **WebhookLog** - Audit trail for webhook deliveries
    - Status: PENDING, SUCCESS, FAILED
    - Tracks: response status, body, response time, retry count

11. **AuditLog** - Comprehensive audit trail
    - Tracks: entity changes, actor, old/new values
    - Stores: IP address, user agent, correlation ID
    - Index optimization for queries by entity type and actor

### Blockchain Integration

12. **BlockchainTransaction** - NFT minting and on-chain operations
    - Types: MINT_NFT, APPROVAL, DOC_UPDATE, REJECT, REVOKE
    - Status: PENDING, CONFIRMED, FAILED
    - Tracks: tx hash, block number, gas used, error messages

## Environment Variables

Set the following in your `.env` file:

```env
# Database Connection
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=goa_gel_db
NODE_ENV=development
```

## Setup Instructions

### 1. Install Dependencies

```bash
npm install typeorm pg uuid crypto
```

### 2. Create Database

```bash
# Using PostgreSQL client
createdb goa_gel_db

# Or using Docker
docker run --name goa_gel_postgres \
  -e POSTGRES_DB=goa_gel_db \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  -d postgres:15-alpine
```

### 3. Run Migrations

```bash
# Run all pending migrations
npx typeorm migration:run -d src/database/data-source.ts

# Generate a new migration (auto-detects schema changes)
npx typeorm migration:generate -d src/database/data-source.ts -n YourMigrationName

# Revert last migration
npx typeorm migration:revert -d src/database/data-source.ts
```

### 4. Seed Database with Sample Data

```bash
# Run the seed script
npx ts-node src/database/seeders/seed.ts
```

After seeding, you'll have:
- 4 sample departments (Fire, Tourism, Municipal, Health)
- 1 RESORT_LICENSE workflow with 5 stages
- 2 sample applicants
- 1 license request in DRAFT status with workflow state

### 5. Verify Setup

```bash
# Connect to the database
psql goa_gel_db

# List tables
\dt

# Check migrations table
SELECT * FROM typeorm_migrations;

# Exit
\q
```

## Entity Relationships Diagram

```
Applicant (1) ──→ (N) LicenseRequest
                       │
                       ├──→ (N) Document ──→ (N) DocumentVersion
                       ├──→ (N) Approval ←─── (1) Department (N)
                       └──→ (1) WorkflowState

Department (1) ──→ (N) Approval
            (1) ──→ (N) Webhook ──→ (N) WebhookLog

Workflow (1) ──→ (N) LicenseRequest

AuditLog - tracks all changes to core entities
BlockchainTransaction - records all on-chain operations
```

## Key Features

### Indexes for Performance
- All frequently queried columns are indexed
- Composite indexes for common query patterns
- JSONB columns for flexible metadata storage

### Cascade Operations
- DELETE cascades properly configured
- Orphaned records cleaned up automatically

### Audit Trail
- Every change tracked in audit_logs
- Actor type and ID recorded
- Old/new values stored for analysis
- IP address and user agent captured

### Blockchain Integration
- All critical operations can be recorded on-chain
- Transaction status tracking
- Error handling with rollback support

### Workflow State Management
- Execution log with full history
- Pending approvals tracking
- Stage transition audit trail
- Extensible for complex workflows

## Common Queries

### Get all license requests for an applicant
```sql
SELECT lr.* FROM license_requests lr
WHERE lr.applicantId = $1
ORDER BY lr.createdAt DESC;
```

### Get pending approvals for a department
```sql
SELECT a.* FROM approvals a
WHERE a.departmentId = $1 AND a.status = 'PENDING'
ORDER BY a.createdAt ASC;
```

### Get audit trail for a specific request
```sql
SELECT al.* FROM audit_logs al
WHERE al.entityType = 'REQUEST' AND al.entityId = $1
ORDER BY al.createdAt DESC;
```

### Get blockchain transaction status
```sql
SELECT bt.* FROM blockchain_transactions bt
WHERE bt.relatedEntityId = $1
ORDER BY bt.createdAt DESC;
```

## Maintenance

### Backup Database
```bash
pg_dump goa_gel_db > backup_$(date +%Y%m%d_%H%M%S).sql
```

### Restore Database
```bash
psql goa_gel_db < backup_file.sql
```

### Monitor Performance
```sql
-- Check table sizes
SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename))
FROM pg_tables
WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

-- Check slow queries
SELECT query, calls, mean_time FROM pg_stat_statements
ORDER BY mean_time DESC LIMIT 10;
```

## Troubleshooting

### Connection Issues
- Verify PostgreSQL service is running
- Check DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD
- Ensure database exists: `createdb goa_gel_db`

### Migration Issues
- Check TypeORM synchronize is false in production
- Ensure migrations run in correct order
- Validate SQL syntax in migration files

### Seeding Issues
- Drop existing data: `npx typeorm schema:drop -d src/database/data-source.ts`
- Re-run migrations and seed
- Check console output for specific errors

## Related Files

- `/src/database/data-source.ts` - TypeORM DataSource configuration
- `/src/database/migrations/` - SQL migration files
- `/src/database/seeders/` - Sample data generators
- `.env` - Environment variables
