RegIntel Care AI - Multi-Hub Compliance Platform

Production-grade multi-tenant compliance platform with dual-hub architecture, adversarial AI auditing, and automated regulatory monitoring

📊 Build Status & Badges

🎯 Project Overview

RegIntel Care AI is a production-ready dual-hub compliance platform (10,000+ LOC) that combines:

Core Architecture

✅ Fail-Closed Multi-Tenancy - PostgreSQL Row-Level Security with 4-layer enforcement
✅ Adversarial AI Auditing - Gemma-3-27B hostile CQC Inspector with structured reasoning
✅ Hash-Chain Audit Trails - Cryptographic integrity verification (SHA-256)
✅ Multi-Channel Notifications - Email/SMS/Webhook/In-app alerts
✅ Async Job Processing - BullMQ with multi-model AI routing

Care Hub (v2.3)

✅ CQC Integration - Official CQC API with facility onboarding
✅ Mock Inspections - AI-powered pre-inspection simulations with SAF gap analysis
✅ Improvement Plans - Automated action plans from current to target ratings
✅ Ground Reports - Frontline staff evidence submission
✅ Geo-Fencing - GPS-based clock-in validation (500m radius)

Immigration Hub (v3.0) 🆕

✅ Visa Dashboard - Traffic light status system (GREEN/AMBER/RED)
✅ Staff Profiles - Complete CRUD for immigration data management
✅ Appendix D Generation - One-click Home Office audit packs (individual + bulk)
✅ 20-Hour Enforcement - Real-time student visa cap with roster write-back
✅ Right-to-Work Tracking - Document expiry monitoring with automated alerts

Compliance Radar (v3.0) 🆕

✅ AI-Powered Monitoring - 24/7 regulatory change detection (CQC, Home Office, Ofsted, HSE)
✅ Impact Analysis - Automatic HIGH/MEDIUM/LOW classification with actionable recommendations
✅ 10 Seeded Sources - Pre-configured regulatory URLs with daily checks
✅ Change Dashboard - Recent updates with review workflow
✅ Custom Sources - Add and monitor any regulatory URL

Ofsted Hub (v3.0) 🆕

✅ Early Years Dashboard - EYFS framework compliance tracking
✅ Inspection History - Record of Ofsted visits and ratings
✅ Compliance Metrics - Real-time monitoring of early years requirements
🔨 Backend Integration - Coming soon (UI ready)

Board Reporting (v3.0) 🆕

✅ Unified Dashboard - Executive overview aggregating all 3 hubs
✅ Risk Metrics - Visa status distribution, compliance percentages
✅ Regulatory Alerts - High-impact changes requiring board attention
✅ Print/Export - One-click PDF generation for stakeholders

System Status: 🟢 v3.0 Complete | 18 unit tests + 22 E2E tests passing | CI/CD Pipeline Active | Production-Ready

🚀 Quick Start

Backend + AI Worker

# 1. Clone and navigate
cd regintel-care-ai

# 2. Start infrastructure (PostgreSQL + Redis)
cd infra/docker && docker compose up -d

# 3. Setup backend (Terminal 1)
cd ../../apps/backend
npm install
npx prisma generate
npm run start:dev  # Port 3000

# 4. Start AI worker (Terminal 2)
cd ../../services/ai-router
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 -u worker.py

# 5. Seed regulatory sources (v3.0)
cd ../../apps/backend
ts-node scripts/seed-radar-sources.ts

Frontend Dashboard

# Terminal 3
cd apps/web
npm install
npm run dev  # Port 3001

Access Points:

🖥️ Frontend Dashboard: http://localhost:3001
🔌 Backend API: http://localhost:3000
📊 Database: localhost:5432 (PostgreSQL)
🔴 Queue: localhost:6379 (Redis)

🏗️ Architecture

The Four Locks (Multi-Layer Security)

graph TB
    A[User Request] --> B[HTTP Middleware: x-tenant-id validation]
    B --> C[AsyncLocalStorage: Request context]
    C --> D[Prisma RLS Extension: Query interception]
    D --> E[PostgreSQL RLS: Row-level filtering]

    F[1. RLS Lock] --> G[Database-level tenant isolation]
    H[2. Visa Shield] --> I[20-hour student visa cap]
    J[3. Geo Fence] --> K[GPS fraud detection - 500m radius]
    L[4. Audit Chain] --> M[SHA-256 hash-chain immutability]

Dual-Hub System Flow (v3.0)

graph LR
    A[Care Hub] --> D[Board Report]
    B[Immigration Hub] --> D
    C[Compliance Radar] --> D
    E[Ofsted Hub] --> D
    
    D --> F[Executive Dashboard]
    
    A -->|Mock Inspections| G[AI Analysis]
    A -->|Improvement Plans| G
    B -->|Visa Alerts| H[Notifications]
    C -->|Regulatory Changes| H
    G --> I[BullMQ Queue]
    I --> J[Python Worker]
    J --> K[Gemma-3-27B]

See ARCHITECTURE.md for detailed system design.

🌐 Frontend Routes (v3.0)

Care Hub

/ - Main dashboard with facility overview
/care/inspections - Mock CQC inspections with AI analysis
/care/improvement - Improvement plans with action items

Immigration Hub 🆕

/immigration/dashboard - Visa traffic light system
/immigration/staff - Staff profiles CRUD with creation modal
/immigration/audit - Appendix D audit pack generation

Ofsted Hub 🆕

/ofsted/dashboard - Early years compliance overview

Compliance Radar 🆕

/radar/alerts - Recent regulatory changes with impact analysis
/radar/sources - Monitored regulatory URLs management

Executive 🆕

/board-report - Unified board-level dashboard

🔧 API Endpoints

Staff Management (v3.0) 🆕

# Create staff member with immigration profile (atomic transaction)
POST /staff/with-immigration
Headers: x-tenant-id: {uuid}
Body: {
  "full_name": "John Doe",
  "visaType": "SKILLED_WORKER",
  "cosNumber": "ABC123456",
  "visaStartDate": "2024-01-01",
  "visaExpiryDate": "2026-12-31",
  "workRestrictionHours": 48,
  "rtwCheckDate": "2025-01-15",
  "rtwCheckedBy": "HR Manager"
}
Response: {
  "staff": { "id": "uuid", "full_name": "John Doe" },
  "immigration": { "visa_type": "SKILLED_WORKER", "visa_status": "GREEN" }
}

# Get all staff for tenant
GET /staff
Headers: x-tenant-id: {uuid}

Immigration Hub (v3.0) 🆕

# Get visa dashboard with traffic light status
GET /immigration/dashboard
Headers: x-tenant-id: {uuid}
Response: {
  "stats": { "green": 45, "amber": 8, "red": 2 },
  "profiles": [
    {
      "staff_id": "uuid",
      "staff_name": "John Doe",
      "visa_status": "AMBER",
      "visa_type": "Skilled Worker",
      "visa_expiry_date": "2026-03-15",
      "documents_complete": true
    }
  ]
}

# Upsert immigration profile
POST /immigration/profiles/:staffId
Headers: x-tenant-id: {uuid}
Body: {
  "visa_type": "STUDENT",
  "visa_expiry_date": "2026-09-30",
  "is_student": true,
  "weekly_hours_limit": 20
}

# Generate Appendix D audit pack (one-click)
GET /immigration/appendix-d/:staffId
Headers: x-tenant-id: {uuid}
Response: {
  "staff_name": "John Doe",
  "sponsor_licence_number": "ABC12345",
  "documents": [...],
  "compliance_checklist": {
    "right_to_work_verified": true,
    "visa_in_date": true
  }
}

# Check shift eligibility (pre-scheduling)
POST /immigration/check-shift-eligibility
Headers: x-tenant-id: {uuid}
Body: {
  "staff_id": "uuid",
  "shift_date": "2025-12-15",
  "shift_duration_hours": 8
}
Response: { "eligible": true, "reason": "..." }

# Validate shift (runtime enforcement)
POST /immigration/validate-shift
Headers: x-tenant-id: {uuid}
Body: {
  "staffEmail": "student@example.com",
  "shiftDurationHours": 6,
  "shiftDate": "2025-12-10"
}
Response 403: {
  "error": "VISA_BREACH_PREVENTED",
  "current_hours": 18,
  "limit": 20
}

Compliance Radar (v3.0) 🆕

# Get recent regulatory changes
GET /radar/recent-changes?days=30
Response: [
  {
    "id": "uuid",
    "regulator": "CQC",
    "impact_level": "HIGH",
    "ai_summary": "New safe staffing guidance requires minimum 1:8 ratio...",
    "actionable_recommendations": [
      "Review current staffing ratios",
      "Update rotas to meet new requirements"
    ],
    "affected_domains": ["SAFE", "WELL_LED"],
    "reviewed": false,
    "detected_at": "2025-12-09T00:05:00Z"
  }
]

# Get unreviewed high-impact changes
GET /radar/high-impact
Response: [...]

# Manual check for specific source
POST /radar/check/:sourceId
Response: {
  "message": "Check completed",
  "changes_detected": true,
  "change_id": "uuid"
}

# Mark change as reviewed
POST /radar/mark-reviewed/:changeId
Response: { "success": true }

Board Reporting (v3.0) 🆕

# Get unified executive dashboard
GET /reporting/board-report
Headers: x-tenant-id: {uuid}
Response: {
  "care_hub": {
    "total_facilities": 12,
    "cqc_ratings": { "Good": 8, "Requires Improvement": 3 },
    "pending_mock_inspections": 2
  },
  "immigration_hub": {
    "total_staff": 55,
    "visa_status_breakdown": { "GREEN": 45, "AMBER": 8, "RED": 2 },
    "student_visa_breaches_blocked": 0
  },
  "compliance_radar": {
    "active_sources": 10,
    "changes_detected_30_days": 7,
    "unreviewed_high_impact": 2
  }
}

CQC Integration (v2.3)

# Onboard facility via CQC location ID
POST /cqc/onboard
Headers: x-tenant-id: {uuid}
Body: { "cqcLocationId": "1-115235818" }
Response: {
  "id": "uuid",
  "cqc_location_id": "1-115235818",
  "provider_name": "Lower Bowshaw View Nursing Home",
  "latest_rating": "Good"
}

# Get all CQC facilities
GET /cqc/metadata
Headers: x-tenant-id: {uuid}

Mock Inspections & Improvement Plans (v2.3)

# Generate improvement plan
POST /inspections/improvement-plan
Headers: x-tenant-id: {uuid}

# Run mock CQC inspection
POST /inspections/mock-inspection
Headers: x-tenant-id: {uuid}

# Submit human verdict
POST /inspections/mock-inspection/:id/verdict
Body: { "verdict": "AGREE|DISAGREE", "notes": "..." }

# Get all improvement plans
GET /inspections/improvement-plans

# Get mock inspections with filter
GET /inspections/mock-inspections?status=PENDING

Shadow Ratings (AI Analysis)

# Submit evidence for adversarial analysis
POST /analysis/shadow-rating
Headers: x-tenant-id: {uuid}
Body: { "evidence": "Medication error: wrong antibiotic administered" }
Response: { "status": "QUEUED", "jobId": "15" }

# Retrieve AI verdicts
GET /analysis/results
Headers: x-tenant-id: {uuid}
Response: [
  {
    "rating": "Inadequate",
    "reasoning": "Evidence demonstrates a serious failure...",
    "regulation": "Regulation 12",
    "reasoning_steps": [...],
    "confidence": 0.87
  }
]

Geo-Fencing (GPS Fraud Detection)

# Single clock-in validation
POST /geo/validate-clock-in
Headers: x-tenant-id: {uuid}
Body: {
  "staffEmail": "jane@example.com",
  "clientId": "uuid",
  "clockInLat": 51.5074,
  "clockInLng": -0.1278
}
Response 200: { "allowed": true, "distance_meters": 120 }
Response 403: { "allowed": false, "distance_meters": 1523, "fraud_event_id": "uuid" }

# Batch validation
POST /geo/validate-batch

Audit Trail (Hash-Chain)

# Query audit logs
GET /audit/logs?action=BLOCK&limit=50
Headers: x-tenant-id: {uuid}

# Verify cryptographic integrity
GET /audit/verify-integrity
Headers: x-tenant-id: {uuid}
Response: {
  "valid": true,
  "total_entries": 1247,
  "chain_breaks": []
}

🧪 Testing Infrastructure (v3.0)

Frontend Tests

cd apps/web

# Vitest unit tests (18 tests)
npm run test

# Playwright E2E tests (22 tests)
npm run test:e2e

# Visual regression tests
npm run test:e2e -- visual-regression.spec.ts

# Specific test suites
npm run test:e2e -- navigation.spec.ts
npm run test:e2e -- immigration-hub.spec.ts
npm run test:e2e -- radar-alerts.spec.ts
npm run test:e2e -- board-report.spec.ts

Test Coverage:

✅ Navigation between 4 hubs (10 pages)
✅ Tenant selector with localStorage persistence
✅ Error handling and graceful degradation
✅ Immigration dashboard with visa traffic lights
✅ Radar alerts with impact filtering
✅ Board report metric aggregation
✅ Visual regression (screenshot comparison)

Backend Tests

cd apps/backend

# Unit tests
npm run test               # All tests
npm run test:watch         # Watch mode
npm run test:cov           # With coverage

# E2E tests
npm run test:e2e

# Specific test
npm run test -- immigration.service.spec

Quality Gates (v3.0) 🆕

Pre-commit Hooks (Husky):

# Automatically runs on git commit:
1. TypeScript compilation (tsc --noEmit)
2. ESLint checks
3. Vitest unit tests
4. Next.js build verification

GitHub Actions CI/CD:

# .github/workflows/frontend-quality-gate.yml
- Runs on every push
- TypeScript + ESLint + Tests + Build
- Playwright E2E suite
- Visual regression checks

Comprehensive Integration Harness

# Requires all services running (DB, Redis, Backend, Worker)
chmod +x scripts/run-all-tests.sh
./scripts/run-all-tests.sh

# Tests 8 critical paths:
# 1. Backend health check
# 2. Database connection (RLS enforcement)
# 3. Geo-fence validation
# 4. Visa cap enforcement
# 5. Shadow rating queue
# 6. Audit log retrieval
# 7. Hash-chain integrity
# 8. Worker status

# Output: 🎉 All Tests PASSED - System Operational

📊 Technology Stack

Component	Technology	Purpose	Lines of Code
Backend API	NestJS + TypeScript	REST API with RLS enforcement	3,500 LOC
Frontend	Next.js 14 + React + TypeScript	Multi-hub dashboard	2,500 LOC
AI Worker	Python 3.11 + Gemini SDK	Multi-model AI routing	316 LOC
Database	PostgreSQL 15 + Prisma	RLS-enforced multi-tenancy	307 LOC (schema)
Queue	Redis + BullMQ	Async job processing	-
AI Models	Gemma-3-27B-IT, Gemini 1.5	Adversarial analysis + monitoring	-
Tests	Playwright + Vitest + Jest	E2E + Unit + Integration	1,500 LOC
Styling	Tailwind CSS + Custom CSS	WCAG AAA accessible UI	186 LOC
CI/CD	GitHub Actions + Husky	Automated quality gates	-
Total	Multi-stack	4 hubs, 10 pages, 40+ endpoints	10,000+ LOC

📁 Project Structure

regintel-care-ai/
├── apps/
│   ├── backend/                          # NestJS API (3,500 LOC)
│   │   ├── src/
│   │   │   ├── analysis/                # Shadow ratings + AI routing
│   │   │   ├── immigration/             # Visa dashboard + enforcement (v3.0)
│   │   │   ├── radar/                   # Regulatory monitoring (v3.0)
│   │   │   ├── reporting/               # Board report aggregation (v3.0)
│   │   │   ├── staff/                   # Staff CRUD module (v3.0)
│   │   │   ├── inspections/             # Mock inspections + plans (v2.3)
│   │   │   ├── common/                  # Geo-fencing + shared services
│   │   │   ├── audit/                   # Hash-chain audit trail
│   │   │   ├── notifications/           # Multi-channel alerts
│   │   │   └── database/                # Prisma + RLS extension
│   │   ├── __tests__/
│   │   │   ├── integration/             # v3.0 feature tests
│   │   │   └── unit/                    # Service unit tests
│   │   ├── scripts/
│   │   │   └── seed-radar-sources.ts    # Seed 10 regulatory URLs
│   │   └── prisma/
│   │       ├── schema.prisma            # 15+ models with RLS
│   │       └── migrations/              # Database migrations
│   └── web/                             # Next.js dashboard (2,500 LOC)
│       ├── src/
│       │   ├── app/
│       │   │   ├── care/                # Care Hub pages
│       │   │   ├── immigration/         # Immigration Hub (v3.0)
│       │   │   ├── ofsted/              # Ofsted Hub (v3.0)
│       │   │   ├── radar/               # Compliance Radar (v3.0)
│       │   │   ├── board-report/        # Board Report (v3.0)
│       │   │   └── dashboard/           # Admin dashboards
│       │   ├── components/
│       │   │   ├── Sidebar.tsx          # Multi-hub navigation (v3.0)
│       │   │   ├── TenantSelector.tsx   # Tenant context (v3.0)
│       │   │   ├── ThemeToggle.tsx      # Dark mode (v3.0)
│       │   │   └── dashboard/           # Reusable components
│       │   └── contexts/
│       │       └── TenantContext.tsx    # Global tenant state (v3.0)
│       └── tests/
│           ├── e2e/                     # Playwright E2E (22 tests)
│           └── unit/                    # Vitest unit tests (18 tests)
├── services/
│   └── ai-router/                       # Python AI worker (316 LOC)
│       ├── worker.py                    # BullMQ consumer + Gemini
│       └── requirements.txt
├── infra/
│   └── docker/
│       ├── docker-compose.yml           # Development infrastructure
│       └── init-scripts/                # 7 SQL migrations
├── .github/
│   └── workflows/
│       └── frontend-quality-gate.yml    # CI/CD pipeline (v3.0)
├── .husky/                              # Pre-commit hooks (v3.0)
├── scripts/
│   └── run-all-tests.sh                # Integration test harness
├── README.md                            # Main project overview
├── CLAUDE.md                            # Developer guide (in root)
├── docs/                                # 📚 All documentation (45+ files)
│   ├── README.md                        # Documentation index
│   ├── ARCHITECTURE.md                  # System design
│   ├── V3_0_DEPLOYMENT_GUIDE.md         # Production deployment
│   ├── TESTING_STRATEGY.md              # Test approach
│   ├── *.md                             # Markdown documentation
│   ├── *.pdf                            # Business documents
│   └── *.docx                           # Strategy documents
└── docker-compose.prod.yml              # Production deployment

🎨 Frontend Features (v3.0)

UI/UX Enhancements

✅ Tenant Context - Global state with localStorage persistence
✅ Next.js API Rewrites - Consistent /api/* routing pattern
✅ Dark Mode - Full support with theme toggle
✅ Sidebar Navigation - 4 hubs with active state indicators
✅ Responsive Design - Mobile-first with Tailwind CSS
✅ Loading States - Skeleton screens and spinners
✅ Error Boundaries - Graceful degradation when backend unavailable

Accessibility (WCAG AAA)

✅ Input Contrast - 14.8:1 contrast ratio (dark text on white background)
✅ Keyboard Navigation - Full keyboard support
✅ Screen Reader Friendly - ARIA labels and semantic HTML
✅ Focus States - Clear visual indicators (2px blue outline)

Developer Experience

✅ TypeScript Strict Mode - Type safety throughout
✅ Consistent Patterns - All features follow Mock Inspections template
✅ Error Handling - Try-catch with user feedback
✅ API Abstraction - Centralized fetch utilities

🔒 Security Features

1. The RLS Lock (Fail-Closed Multi-Tenancy)

// Without tenant context? Query returns [], not all data
if (!context.tenantId) {
  throw new Error('Tenant context required');
}

Four-Layer Enforcement:

HTTP Middleware - Enforces x-tenant-id header
AsyncLocalStorage - Request-scoped context
Prisma RLS Extension - Intercepts ALL queries
PostgreSQL RLS - Database-level row filtering

Critical: Uses app_user role (non-superuser) to prevent RLS bypass.

2. The Visa Shield (Immigration Compliance)

// 20-hour/week student visa cap - hard block
if (projectedTotal > 20) {
  // Automatically triggers:
  // 1. Roster write-back to Deputy/Nourish
  // 2. CRITICAL notification to compliance team
  // 3. Audit log entry with hash-chain
  
  throw new ForbiddenException('VISA_BREACH_PREVENTED');
}

3. The Geo Fence (GPS Fraud Detection)

// Haversine distance calculation
const distance = calculateDistance(
  clockInLat, clockInLng,
  clientLat, clientLng
);

if (distance > 500) {
  // Log fraud event (append-only)
  // Trigger audit entry
  throw new ForbiddenException('GEO_FENCE_VIOLATION');
}

4. The Audit Chain (Cryptographic Integrity)

-- Each entry hashes: previous_hash + current_data (SHA-256)
CREATE TABLE audit_log (
  current_hash VARCHAR(64),
  previous_hash VARCHAR(64)
);

-- Trigger blocks UPDATE/DELETE (append-only)
CREATE TRIGGER audit_immutable BEFORE UPDATE OR DELETE ON audit_log
  FOR EACH ROW EXECUTE FUNCTION reject_audit_modifications();

5. The AI Inspector (Adversarial Auditing)

Prompt Strategy: Epistemic Stratification

ROLE: You are a hostile CQC Inspector.
RULES:
1. Assume the provider is hiding failures.
2. Flag "Missing Evidence".
3. Cite specific regulation breaches.
4. Provide step-by-step reasoning.

Output:

{
  "rating": "Inadequate",
  "reasoning": "Evidence demonstrates a serious failure...",
  "regulation": "Regulation 12",
  "reasoning_steps": [...],
  "confidence": 0.87
}

🚢 Production Deployment

# Build and run all services
docker compose -f docker-compose.prod.yml up -d

# Services launched:
# - postgres:15-alpine (RLS-enforced)
# - redis:alpine (BullMQ queue)
# - backend (NestJS on port 3000)
# - frontend (Next.js on port 3001)
# - worker (Python AI consumer)

# Health checks
curl http://localhost:3000/                         # Backend → 200 OK
curl http://localhost:3001/                         # Frontend → 200 OK
docker exec regintel-queue redis-cli ping           # Redis → PONG
docker exec regintel-db pg_isready -U app_user      # PostgreSQL → ready

📈 Performance Characteristics

Metric	Value	Notes
API Response Time	<50ms	Job queuing only (202 Accepted)
AI Processing Time	5-15 seconds	Gemma-3-27B inference
Frontend Load Time	<2 seconds	Next.js SSR + code splitting
Database Latency	<10ms	RLS adds ~1ms overhead
RLS Enforcement	100% coverage	All queries require tenant context
Geo Calculation	<1ms	Haversine in-memory
Hash Verification	~50ms/1000 entries	SHA-256 sequential

🌟 Feature Highlights

v3.0: Dual-Hub Expansion 🆕

✅ Immigration Hub with visa traffic light system
✅ Compliance Radar with AI-powered monitoring
✅ Ofsted Hub with EYFS compliance tracking
✅ Board Reporting with unified metrics
✅ Staff CRUD with atomic transactions
✅ Frontend quality gates (Playwright + Vitest)
✅ Dark mode support
✅ WCAG AAA accessibility (14.8:1 contrast)
✅ Comprehensive testing (40 tests total)

v2.3: Care Hub Foundation

✅ CQC API integration
✅ Mock inspections with AI
✅ Improvement plans
✅ Ground reports
✅ Geo-fencing fraud detection

v2.2: Core Platform

✅ Fail-closed multi-tenancy
✅ Adversarial AI auditing
✅ Hash-chain audit trails
✅ Multi-channel notifications
✅ Roster integration

📊 Code Statistics (v3.0)

Component	Files	Lines of Code	Technology
Backend API	60+	3,500	NestJS + TypeScript
Frontend	40+	2,500	Next.js + React
AI Worker	1	316	Python + Gemini SDK
Tests (Backend)	8	400	Jest + Supertest
Tests (Frontend)	9	1,100	Playwright + Vitest
SQL Migrations	7	500	PostgreSQL + RLS
Documentation	15+	1,500	Markdown
Infrastructure	5	184	Docker + CI/CD
Grand Total	140+	10,000+	Multi-stack

📚 Documentation

All documentation has been organized into the docs/ directory for easy navigation.

Core Documentation

CLAUDE.md - Comprehensive developer guide (in project root, 1,200+ LOC)
docs/ARCHITECTURE.md - System design with Mermaid diagrams
docs/V3_0_DEPLOYMENT_GUIDE.md - Production deployment
docs/STARTUP_GUIDE.md - Getting started guide
docs/CI_CD_GUIDE.md - CI/CD pipeline guide

Testing Documentation

docs/TESTING_STRATEGY.md - Comprehensive test approach
docs/QUALITY_GATE_IMPLEMENTATION.md - CI/CD setup
docs/TEST_RESULTS_SUMMARY.md - Test execution results

Version Reports

docs/V3_0_COMPLETION_SUMMARY.md - v3.0 completion summary
docs/V2_3_COMPLETION_REPORT.md - v2.3 completion report
docs/FEATURES_IMPLEMENTATION_COMPLETE.md - v3.0 feature overview

Business Documents

Product Requirements PDFs and business strategy documents in docs/

Reference

Prisma Schema - Database models with RLS
SQL Migrations - 7 migration files
API Reference - Complete endpoint documentation

Complete Index

See docs/README.md for a complete documentation index with all 45+ documents organized by category.

🎓 Key Learnings

1. RLS with Complex Joins

Issue: Prisma queries with nested relations can fail RLS checks. Solution: Separate queries - fetch IDs first, then related data:

const staffIds = await prisma.staffProfile.findMany({ select: { id: true } });
const profiles = await prisma.immigrationProfile.findMany({ 
  where: { staffId: { in: staffIds } } 
});

2. Global Tables Without tenant_id

Issue: Tables like regulatory_changes are global (no tenant_id). Solution: Use $queryRawUnsafe to bypass RLS for global data:

const changes = await prisma.$queryRawUnsafe<any[]>(`
  SELECT * FROM regulatory_changes WHERE detected_at >= $1
`, since);

3. Superuser RLS Bypass

Issue: PostgreSQL superusers bypass ALL RLS policies. Solution: Use non-superuser app_user role:

DATABASE_URL=postgresql://app_user:app_password@localhost:5432/regintel_v2

4. Frontend Input Contrast

Issue: Light text on light background = invisible typing. Solution: Global CSS with explicit color declarations:

input { background-color: #ffffff; color: #1e293b; }

5. Tenant Context in API Calls

Issue: 401 errors when x-tenant-id header missing. Solution: Global TenantContext with React hooks:

const { tenantId } = useTenant();
fetch('/api/...', { headers: { 'x-tenant-id': tenantId } });

🎉 What's New in v3.0

Major Features

Immigration Hub - Complete visa management system
Compliance Radar - AI-powered regulatory monitoring
Ofsted Hub - Early years compliance tracking
Board Reporting - Executive dashboard
Staff Module - Full CRUD with immigration profiles

Frontend Enhancements

Tenant Context - Global state management
Dark Mode - Full theme support
WCAG AAA - 14.8:1 input contrast
10 Pages - Complete multi-hub navigation
Quality Gates - Pre-commit hooks + CI/CD

Testing Infrastructure

Playwright E2E - 22 tests covering 5 suites
Vitest Unit - 18 component tests
Visual Regression - Screenshot comparison
Pre-commit Hooks - TypeScript + ESLint + Tests
GitHub Actions - Automated quality gates

Bug Fixes

✅ Fixed 401 errors (missing tenant headers)
✅ Fixed 500 on board report (RLS queries)
✅ Fixed input contrast issues (global CSS)
✅ Fixed visa dashboard joins (separated queries)
✅ Fixed radar service (raw SQL for global data)

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

AI Models: Google Gemma-3-27B-IT (open-source), Gemini 1.5 Flash
Frameworks: NestJS, Next.js 14, Prisma, BullMQ, Playwright
Inspiration: UK compliance frameworks (CQC, Home Office, Ofsted)
Database: PostgreSQL Row-Level Security implementation

🤝 Contributing

This is a portfolio project demonstrating production-grade patterns:

Fail-closed multi-tenancy with database-level isolation
Adversarial AI prompting with structured reasoning
Dual-hub architecture with unified reporting
Cryptographic audit trails with hash-chain integrity
Comprehensive testing with quality gates
WCAG AAA accessible UI design

For questions or feedback, see the documentation files listed above.

Built with adversarial rigor 🔍 | Secured with fail-closed design 🔒 | Powered by Gemma-3-27B + Gemini 1.5 🤖 | 10,000+ LOC 📊

System Status: 🟢 OPERATIONAL | v3.0 Complete | 40 Tests Passing | Quality Gates Active | Production-Ready

Last Updated: December 10, 2025 | Version: 3.0.0 | Commit: f83f877

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
.husky		.husky
apps		apps
backups		backups
docs		docs
infra/docker		infra/docker
scripts		scripts
services/ai-router		services/ai-router
.gitignore		.gitignore
.project-structure		.project-structure
CLAUDE.md		CLAUDE.md
Dockerfile.backend		Dockerfile.backend
Dockerfile.worker		Dockerfile.worker
LICENSE		LICENSE
README.md		README.md
audit_codebase.sh		audit_codebase.sh
docker-compose.prod.yml		docker-compose.prod.yml
fix_and_launch.sh		fix_and_launch.sh

Folders and files

Latest commit

History

Repository files navigation

RegIntel Care AI - Multi-Hub Compliance Platform

📊 Build Status & Badges

🎯 Project Overview

Core Architecture

Care Hub (v2.3)

Immigration Hub (v3.0) 🆕

Compliance Radar (v3.0) 🆕

Ofsted Hub (v3.0) 🆕

Board Reporting (v3.0) 🆕

🚀 Quick Start

Backend + AI Worker

Frontend Dashboard

🏗️ Architecture

The Four Locks (Multi-Layer Security)

Dual-Hub System Flow (v3.0)

🌐 Frontend Routes (v3.0)

Care Hub

Immigration Hub 🆕

Ofsted Hub 🆕

Compliance Radar 🆕

Executive 🆕

🔧 API Endpoints

Staff Management (v3.0) 🆕

Immigration Hub (v3.0) 🆕

Compliance Radar (v3.0) 🆕

Board Reporting (v3.0) 🆕

CQC Integration (v2.3)

Mock Inspections & Improvement Plans (v2.3)

Shadow Ratings (AI Analysis)

Geo-Fencing (GPS Fraud Detection)

Audit Trail (Hash-Chain)

🧪 Testing Infrastructure (v3.0)

Frontend Tests

Backend Tests

Quality Gates (v3.0) 🆕

Comprehensive Integration Harness

📊 Technology Stack

📁 Project Structure

🎨 Frontend Features (v3.0)

UI/UX Enhancements

Accessibility (WCAG AAA)

Developer Experience

🔒 Security Features

1. The RLS Lock (Fail-Closed Multi-Tenancy)

2. The Visa Shield (Immigration Compliance)

3. The Geo Fence (GPS Fraud Detection)

4. The Audit Chain (Cryptographic Integrity)

5. The AI Inspector (Adversarial Auditing)

🚢 Production Deployment

📈 Performance Characteristics

🌟 Feature Highlights

v3.0: Dual-Hub Expansion 🆕

v2.3: Care Hub Foundation

v2.2: Core Platform

📊 Code Statistics (v3.0)

📚 Documentation

Core Documentation

Testing Documentation

Version Reports

Business Documents

Reference

Complete Index

🎓 Key Learnings

1. RLS with Complex Joins

2. Global Tables Without tenant_id

3. Superuser RLS Bypass

4. Frontend Input Contrast

5. Tenant Context in API Calls

🎉 What's New in v3.0

Major Features

Frontend Enhancements

Testing Infrastructure

Bug Fixes

📄 License

🙏 Acknowledgments

🤝 Contributing