# HCMS Compliance Shield — Claude Code Working Document

**Read this on every Claude Code session before touching code.**

---

## Identity

You are working on the **HCMS Compliance Shield** — the shared microservice that codifies Suriname compliance rules for consumption by all HCMS Sovereign App Suite applications.

- Owner: HCMS N.V. (subsidiary of K&K Heritage Group N.V.)
- Service Owners: HCMS Compliance Advisor (business) + IQT Lead (technical)
- Position: Shared Infrastructure / 3rd FO of HCMS App Suite
- Consumers v1: HUMANABLE (Pillar I) + ATLAS (Pillar II)
- Consumers v2+: HCMS Academy + HCMS Digi Coaches + K&K Heritage Group expansion apps
- Authoritative spec: `HCMS-FO-ComplianceShield-v1.0-2026.md`

## What this service IS

- A Laravel microservice with a versioned REST API at `/api/v1/*`.
- Source of truth for Suriname compliance rules (stored in `rule_versions`).
- The audit trail for EU AI Act decisions across all HCMS apps.
- The GDPR Subject Request orchestrator for HCMS apps.
- The bias-detection, tax pre-flight, work permit pre-screening, Article 1639 detection, Local Content reporting, and Right-to-Work verification service.

## What this service IS NOT

- NOT public-facing. Bind to `localhost:8003`, expose via Nginx on `compliance-shield.internal` only.
- NOT a feature inside HUMANABLE or ATLAS — it is a separate deployment.
- NOT a place to hardcode compliance rules — rules live in the `rule_versions` table.
- NOT a consumer of HUMANABLE or ATLAS — calls flow one way: consumers call us.

## Critical rules (never violate)

1. NO Docker. NO Kubernetes. NO containers.
2. NO Redis. Use Laravel database drivers for cache/queue/session.
3. NO Meilisearch. Use PostgreSQL FTS + pgvector when needed.
4. NO AWS managed services. NO Supabase. NO Firebase.
5. NEVER expose this service publicly. Internal-only.
6. NEVER hardcode Suriname compliance rules. Use the `rule_versions` table.
7. NEVER let audit logging fail silently — `AuditLogger` must `report()` failures to Sentry.
8. Every authenticated endpoint MUST require Sanctum service-token auth.
9. Every API call MUST be logged to `request_log` via `LogComplianceRequest` middleware.
10. Every module response MUST stamp `X-Rule-Version-Applied` (handled by `StampRuleVersion` middleware).
11. Every business decision MUST be logged to its module-specific audit table.

## Tech stack (locked)

| Layer | Choice |
| :---- | :---- |
| Framework | Laravel 13 |
| Language | PHP 8.3+ (running on PHP 8.4 in dev) |
| Local DB | SQLite |
| Production DB | PostgreSQL 16 + pgvector (schema `compliance_shield`) |
| API style | REST, versioned at `/api/v1/` |
| Authentication | Laravel Sanctum service tokens, `tokenable = App\Models\ConsumerApp` |
| Admin Panel | Filament 4 (Phase 0 deviation from FO §11 — Filament 3 does not support Laravel 13; documented in Phase 0 handoff) |
| Cache / queue / session | Laravel `database` driver |
| Background jobs | Laravel queue worker (systemd-managed `compliance-shield-queue.service`) |
| Monitoring | Laravel Pulse + self-hosted Sentry |
| Web server | Nginx (reverse proxy on localhost only) |
| Hosting | Shared LiquidNet US VPS (with HUMANABLE + ATLAS) |
| Port | 8003 |
| Network exposure | Internal-only (localhost / VPN) |

## Shared VPS topology

```
LiquidNet US VPS (16 GB RAM · 6 vCPU · 400 GB SSD)
├── humanable.hcmsnv.com         → :8001
├── atlas.hcmsnv.com             → :8002
└── compliance-shield.internal   → :8003 (this service — internal only)

PostgreSQL 16 + pgvector
├── humanable          schema
├── atlas              schema
└── compliance_shield  schema (this service)
```

## The 8 modules (FO §3)

| # | Module | Internal slug | Phase |
| :---- | :---- | :---- | :---- |
| 1 | 38% Expat Income Tax Pre-Flight | `tax_pre_flight` | 3 |
| 2 | Article 1639 Seniority Liability Flag | `article_1639` | 4 |
| 3 | Work Permit Pre-Screening | `work_permit` | 3 |
| 4 | Local Content Auto-Reporter | `local_content` | 5 |
| 5 | **EU AI Act Compliance Layer** | `ai_act` | **2 — FIRST** |
| 6 | Bias Detection | `bias_detection` | 5 |
| 7 | GDPR Subject Request Portal | `gdpr` | 2 (alongside Module 5) |
| 8 | Right-to-Work Verification | `right_to_work` | 4 |

Phase 0 has shipped SKELETON endpoints for all 8 modules — every endpoint returns 501 with `module` and `rule_version_applied` populated. Full module logic lands Phases 2–5.

## Versioning strategy

- API versioned at URL prefix `/api/v1/`.
- Compliance rules versioned in `rule_versions` table; recommended format `YYYY-Qn-NNN` (FO §12.2 OQ #5).
- `StampRuleVersion` middleware writes the active version into the request, and `LogComplianceRequest` persists it to `request_log` and emits the `X-Rule-Version-Applied` response header.
- Consumer apps log this header for cross-app audit trail.
- Rule updates are deployed independently of code releases.

## Consumer integration pattern

```php
// In HUMANABLE or ATLAS:
$response = Http::withToken(config('services.compliance_shield.token'))
    ->acceptJson()
    ->post(config('services.compliance_shield.url').'/api/v1/tax/pre-flight', [
        // payload
    ]);
```

- Service token: long-lived, stored in consumer app `.env`, rotated quarterly (configurable via `COMPLIANCE_SHIELD_TOKEN_ROTATION_MONTHS`).
- Consumer apps can be scoped to specific modules via `ConsumerApp::$allowed_modules`. An empty/null allowlist means full access.

## Failure mode (critical)

If the Compliance Shield is unreachable, consumer apps MUST:

- BLOCK the workflow step that needed a compliance check
- Log to Sentry
- Alert the Operations Manager
- NEVER silently skip the check — compliance is non-negotiable

This is intentional. The whole point of the moat is that it can't be bypassed.

## Repository layout (Phase 0)

```
compliance-shield/
├── app/
│   ├── Http/
│   │   ├── Controllers/V1/   (HealthController, RuleVersionController, StubController)
│   │   └── Middleware/       (LogComplianceRequest, StampRuleVersion, EnsureModuleAccess)
│   ├── Models/               (ConsumerApp, RuleVersion, RuleUpdateAudit, RequestLog, ErrorLog,
│   │                          AiDecisionAudit, TaxCalculation, Article1639Flag,
│   │                          WorkPermitScreening, LocalContentReport, BiasScan,
│   │                          GdprRequest, GdprRequestDataPackage, RightToWorkVerification, User)
│   ├── Services/             (RuleEngine, AuditLogger, ConsumerAppRegistry)
│   └── Providers/Filament/   (AdminPanelProvider)
├── bootstrap/                (app.php — JSON-only error handling for /api/*)
├── config/                   (compliance-shield.php + standard Laravel configs)
├── database/
│   ├── migrations/           (14 service tables + Sanctum + framework + Pulse + Permission)
│   └── seeders/              (AdminUserSeeder, ConsumerAppSeeder, DatabaseSeeder)
├── docs/
│   └── handoffs/phase-0.md
├── routes/api.php            (versioned endpoints under /api/v1/)
├── tests/Feature/            (HealthEndpointTest, ServiceTokenAuthTest, RequestLoggingTest)
├── .env.example
├── CLAUDE.md
└── README.md
```

## Behavioural defaults

- Read the FO (`HCMS-FO-ComplianceShield-v1.0-2026.md`) before any architectural decision.
- Atomic commits, descriptive messages.
- Every authenticated endpoint passes Sanctum + `EnsureModuleAccess` + `StampRuleVersion` — no exceptions.
- Every endpoint returns `X-Rule-Version-Applied` and `X-Correlation-Id` headers.
- Every business decision is logged to its module-specific audit table.
- Never assume scope expansion — if a task exceeds the current phase, stop and ask.
- Update this CLAUDE.md when the team learns something the next agent needs to know.

---
*Last updated: 2026-05-25 · Maintained by: IQT Lead · Authoritative source: HCMS-FO-ComplianceShield-v1.0-2026.md*