Project Guide | Regulated Case Workbench

Regulated Case Workbench

regulated-case-workbench is a user-friendly FastAPI demo for regulated case operations.

It keeps case intake, grounded evidence review, redaction preview, reviewer assignment, policy gating, signed export proof, and cross-case auditability in one inspectable surface.

Public proof stays on the live surface at https://regulated-case-workbench.pages.dev, while the GitHub repo remains selectively shared.

• Private pilot path: scope one secure workflow without posting regulated records, personal data, credentials, or production logs.

System Overview

A regulated workflow desk that demonstrates controlled approvals, signed evidence, and staged review without leaking sensitive cases.

Evaluation Path

• Start here: Open the live surface, then verify signed export and audit trail behavior locally.
• Local demo: Run make run, then open http://127.0.0.1:8000.
• Checks: Run make verify; it covers compile checks, pytest, frontend syntax validation, and runtime scorecard exercise.

Technical Notes

• Technical guide summarizes the system scope, first files to inspect, verification commands, and known boundaries.
• Quality notes lists the local checks, CI surface, and release expectations for this repository.
• Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

Architecture at a glance

• API runtime: app/main.py exposes the regulated workflow routes.
• Guard rails: app/operator_access.py adds optional token + role checks for sensitive routes.
• Runtime evidence: app/runtime_store.py persists route/policy/signature events to local JSONL.
• Workbench UI: app/static/ is a lightweight vanilla JS reviewer desk.
• Static front door: site/ is a static landing page for GitHub/Pages-style review.
• Infra: Dockerfile, .github/workflows/, and infra/terraform/ show deployability and repo maturity.
• Regression checks: tests/ locks the API and key frontend contract surfaces.

Runtime vs. review/site surfaces

• Primary runtime: the FastAPI app in app/ plus the local operator UI in app/static/.
• Review/site surfaces: site/ and docs/ are supporting docs and static walkthrough material, not the live queue runtime.
• Repo map: scripts/ contains exercise helpers, tests/ contains regression checks, and infra/ contains deployment notes.

What it demonstrates

• A regulated workflow product instead of a generic chat shell
• Grounded case summaries tied to explicit evidence items
• Redaction safety and reviewer signoff before export
• Timeline-backed case history, policy gate, and export manifest preview
• Reviewer assignment, handoff brief, cross-case audit feed, and signed export proof
• Runtime brief, scorecard, summary pack, schema routes, and CI
• Inbox search, priority/stage filters, case-route chips, and clickable audit feed rows so reviewers can navigate the workbench like a real queue

Option A: simple dev flow

make install
make run

Open http://127.0.0.1:8000.

Option B: manual setup

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
uvicorn app.main:app --reload

Optional operator auth demo

Sensitive routes stay open by default for easy review. To show route guarding locally:

export REGULATED_CASE_OPERATOR_TOKEN=regulated-token
export REGULATED_CASE_OPERATOR_ALLOWED_ROLES=reviewer,approver
uvicorn app.main:app --reload

Then call guarded routes with:

curl -H "Authorization: Bearer ${REGULATED_CASE_OPERATOR_TOKEN}" \
  -H 'x-operator-role: reviewer' \
  'http://127.0.0.1:8000/api/export-pack/signature?case_id=case-1007'

Runtime surfaces

• GET /health
• GET /api/meta
• GET /api/runtime/brief
• GET /api/resource-pack
• GET /api/runtime/scorecard
• GET /api/release-readiness
• GET /api/release-risk-board
• GET /api/release-evidence-board
• GET /api/release-readiness/schema
• GET /api/summary-pack
• GET /api/review-summary
• GET /api/review-summary/schema
• GET /api/multimodal-intake-pack
• GET /api/schema/case-report
• GET /api/schema/export-manifest
• GET /api/cases
• GET /api/cases/{case_id}
• GET /api/cases/{case_id}/evidence
• GET /api/cases/{case_id}/timeline
• GET /api/handoff-brief
• GET /api/reviewer-assignment
• GET /api/policy/check
• GET /api/redaction-preview
• GET /api/export-pack/preview
• GET /api/export-pack/signature
• GET /api/audit/feed
• GET /api/evals/review-scenarios

Devex shortcuts

make test
make scorecard
make verify

make verify runs compile checks, pytest, frontend syntax validation, and the runtime scorecard exercise.

Local verification

make verify

Manual equivalent:

python -m pip install -U pip
python -m pip install -e ".[dev]"
python3 -m compileall -q app tests
python -m pytest
node --check app/static/app.js
python scripts/exercise_runtime_scorecard.py

Related docs

• docs/multimodal-intake-pack.md — intake lanes and release boundaries
• docs/deployment/CLOUDFLARE_PAGES.md — static front-door deployment note
• infra/terraform/README.md — infrastructure notes

Deliberate constraints

• Synthetic data only
• No database dependency; runtime evidence is persisted as local JSONL for inspectability
• Vanilla JS frontend to keep the dashboard obvious and low-overhead
• Minimal dependency set so the workflow story stays front and center

Cloud + AI Architecture

• Cloud + AI architecture blueprint
• Machine-readable architecture manifest
• Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

• Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

Service Architecture

• Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.