WCP Compliance Agent V5

Production-ready WH-347 compliance platform: deterministic validation decides, the LLM explains, and every decision is traceable.

V5 is a five-service monorepo where each service has one clear responsibility. A payroll flows through extraction, deterministic validation, Mastra-based verdict synthesis, trust scoring, and audited persistence with request and trace IDs propagated across service boundaries.

Shipped proof: 377 tests across five services, plus four tooling checks. The current TypeScript gate covers 42 Contracts, 70 Agent, 45 Gateway, and 30 Web tests; Compliance Core passed 89 unit tests and 101 eval tests over 100 golden examples and one baseline regression. The offline portfolio path runs without credentials, Docker, Redis, PostgreSQL, or network access. The Python 3.12/Poetry and optional-infrastructure gates run in CI.

Portfolio demo

Thesis: deterministic compliance checks decide the verdict; the LLM only explains the audit record.

pnpm install --frozen-lockfile
pnpm demo:ui

Open http://localhost:5173 — mock mode auto-authenticates and loads sample data with a quiet Sample data badge in the sidebar.

Click path:

1. Review Queue — one pending case for job-wh347-demo-2026 (42% trust, rejected).
2. Inspect Audit — three deterministic violations, regulatory citations, and the LLM explanation paragraph; compliance checks decided the verdict.
3. Analyze Payroll (optional) — paste any WH-347 text and run the five-step pipeline (Extract → Validate → Explain → Trust → Persist) to the same rejected outcome.
4. Contracts, Payrolls, Ingestion, or Analytics — the same demo IDs appear across routes.

---

Architecture

Web (React 19) -> Gateway (Hono) -> Agent (Mastra)
                      |                |
                      |                -> Compliance Core (FastAPI) for extraction/validation
                      |
                      -> Data Platform (FastAPI + SQLAlchemy) for persistence/querying

Service	Language	Port	Responsibility	Why It Exists
Web	TypeScript/React 19	5173	Upload flow, decision display, analytics, review queue	UI state management
Gateway	TypeScript/Hono	3000	Auth, CORS, rate limiting, routing, SSE streaming	Single entry point, security boundary
Agent	TypeScript/Mastra	3001	LLM orchestration, verdict synthesis, trust scoring, persistence handoff	LLM integration isolated from database writes
Compliance Core	Python/FastAPI	8000	Deterministic extraction, wage validation, DBWD lookup	Source of compliance truth
Data Platform	Python/FastAPI + SQLAlchemy	8001	Decision persistence, audit events, contracts, payrolls, analytics	Single source of truth for stored data

Critical boundary rule: The Agent never writes to the database directly. Its Mastra workflow submits TrustScoredDecision objects to the Data Platform via /internal/decisions, and the Data Platform is the only service that persists official decision records and audit events. Compliance Core never persists; it returns structured extraction and validation results.

Quick Start

Prerequisites and install

• Node.js 20 and pnpm 9.15.0 (the exact pnpm version is declared in package.json). Install via npm i -g [email protected] — do not rely on the corepack shim.
• Python 3.12 and Poetry 1.8.5 for the two Python services.
• Nothing else: no Docker, database, Redis, LLM key, or make for the credential-free paths below. Docker/PostgreSQL/Redis/provider keys are optional expansions for the full-workflow and real modes at the bottom.

pnpm install --frozen-lockfile

cd apps/compliance-core
poetry config virtualenvs.in-project true
poetry install --no-interaction

cd ../data-platform
poetry config virtualenvs.in-project true
poetry install --no-interaction

Poetry’s default cache-based virtualenv does not create apps/*/.venv, which the credential-free evidence script uses to invoke Compliance Core and Data Platform. The in-project setting matches the CI TypeScript/evidence job.

Credential-free portfolio proof

pnpm evidence
pnpm test:e2e

pnpm evidence executes the fixed five-service scenario through local adapters, writes a normalized bundle under artifacts/portfolio/, verifies its checksums, and compares it with the tracked golden fixture. pnpm test:e2e runs desktop and mobile browser smoke tests with VITE_MOCK_API=true. See Portfolio Evidence for the bundle and replay contract.

UI Mock Mode

git clone <repo-url> && cd wcp-compliance-agent-v5
pnpm install --frozen-lockfile

VITE_MOCK_API=true WCP_MOCK_AUTH=true pnpm dev

Open http://localhost:5173.

Full Local Workflow Mock Mode

Optional expansion — needs Docker. LLM_MODE=mock avoids LLM API keys, but the Agent workflow still calls Compliance Core and Data Platform.

cd infra
docker compose up -d postgres redis

cd ../apps/compliance-core
poetry install --no-interaction
poetry run uvicorn wcp_compliance.main:app --port 8000

cd ../data-platform
poetry install --no-interaction
poetry run alembic upgrade head
poetry run uvicorn wcp_data.main:app --port 8001

cd ../..
LLM_MODE=mock WCP_MOCK_AUTH=true pnpm dev

Real Mode

Optional expansion — needs Docker and a provider API key.

cd infra
docker compose up -d postgres redis

cd ../apps/data-platform
poetry run alembic upgrade head

cd ../..
LLM_MODE=real OPENAI_API_KEY=sk-... pnpm dev

Pipeline

Upload WH-347 (PDF or text)
  |
  |- 1. EXTRACT  Compliance Core parses into ExtractedWCP
  |- 2. VALIDATE Rule engine checks wages, overtime, fringe, signature, totals, classification
  |- 3. VERDICT  Mastra Agent synthesizes verdict with RAG context and citations
  |- 4. TRUST    Four-component weighted score (35/25/20/20)
  `- 5. PERSIST  Data Platform creates DecisionRecord + AuditEvent atomically

Current Verification State

Layer	Current count	Runner	Status
Compliance Core unit tests	84	pytest	Passed locally in the project virtual environment
Compliance Core eval tests	101	pytest	100 examples plus one baseline regression passed
Data Platform unit/integration	command gate	pytest	Python 3.12/Poetry CI job; PostgreSQL and Redis are service fixtures for integration
Agent tests	66	vitest	Passed in the finalization gate
Gateway tests	45	vitest	Passed in the finalization gate
Web tests	30	vitest	Passed in the finalization gate
Contracts tests	42	vitest	Passed in the finalization gate
Tooling contract tests	4	node:test	Passed in the finalization gate
Browser smoke	2	Playwright	Desktop Chromium-compatible Chrome and 390x844 mobile passed
Portfolio evidence	1 bundle	SHA-256 verifier	Passed with reproducibility hash pinned in the fixture

pnpm test                               # TypeScript and tooling tests via Turborepo
pnpm test:golden                        # Compliance Core golden-set regression gate
pnpm evidence                           # Generate and verify the offline evidence bundle
pnpm test:e2e                           # Desktop and mobile browser smoke tests in UI mock mode
cd apps/compliance-core && poetry run pytest tests/unit tests/eval -v
cd apps/data-platform && poetry run pytest tests/unit tests/integration -v

Key Design Decisions

• Deterministic validation is the source of compliance truth: the LLM adds explanation and citations, not correctness.
• Agent never writes to the database directly: its Mastra workflow submits TrustScoredDecision; Data Platform creates official records.
• Every decision is traceable: x-request-id and x-trace-id propagate through the pipeline and persistence layer.
• Mock modes are scoped: VITE_MOCK_API=true runs the UI without backend services; LLM_MODE=mock runs Agent workflows without LLM API keys.
• Offline composition is a proof adapter, not a new source of truth: it invokes the canonical Compliance Core engine, then exercises Agent, Data Platform, cache, SSE, audit, and UI-fixture contracts in one deterministic scenario.
• Safe verdict override: LLM approval is overridden to rejected when deterministic violations exist.

Project Structure

apps/
  web/              React 19 + Vite + Shadcn/ui
  gateway/          Hono + Zod + jose
  agent/            Mastra + AI SDK v6 + Langfuse
  compliance-core/  FastAPI + Pydantic v2 + pdfplumber
  data-platform/    FastAPI + SQLAlchemy + Alembic
packages/
  contracts/        JSON schemas -> codegen (TS + Python)
  observability/    Trace context types
  typescript-client/ ServiceClient with GET/POST/DELETE + timeout
  test-fixtures/    Sample WH-347 files
docs/
  architecture/     Request flow, data ownership, data model, evolution, case study
  adrs/             Architecture decision records
  planning/         Plans, porting audit, known gaps
  operations/       Deployment guide

Documentation

• Request Flow
• Service Boundaries
• Data Ownership
• Data Model
• V2 to V5 Evolution
• Case Study
• ADR Index
• Setup and Entry Points
• Security
• Failure Modes
• Testing
• Portfolio Evidence
• Known Gaps
• Deployment Guide

The documents under docs/planning/ that describe the V3/V4 port are historical execution records. Current capability and deferred-boundary claims live in this README, docs/planning/v5-known-gaps.md, and the operational documents above.

Part of the stack

groundtruth · evalforge · llm-gateway · aria-agent · agenttrace

License

MIT