Janady13/missionmatch / CLAUDE.md

1# missionMATCH / slateMATCH / screenMATCH — Project Context for Claude Code 2 3## What this is 4A **Cleared Workforce Intelligence Platform** for US government contractors, cleared staffing 5firms, proposal teams, and capture teams. NOT a generic ATS. The whole product serves the loop: 6**Requirement → Candidate Intelligence → Match Scoring → Ranked Candidate Slate → Proposal Readiness.** 7slateMATCH (requirement-to-slate) is the core differentiator. 8 9## Hard rules (tooling and writing style, non negotiable) 101. No Python anywhere. Backend is Go, frontend is TypeScript and Node, scripts are bash. Never add a Python script, tool, or dependency. HTML is written by hand, never generated by a program. 112. No dashes of any kind in written output: code comments, log strings, UI copy, docs, and commit messages. Use commas, periods, or rewrite the sentence. Hyphens that are required syntax are allowed inside URLs, HTTP header names, CLI flags, and code identifiers (package names, file names, npm script keys). 123. Every API key stays on the server only. All keys load from `/etc/missionmatch/sam-sync.env` on Bubbles, a root owned 0600 file that is never web served and never in the repo. Placeholder names live in `.env.example` and the real env file is covered by `.gitignore`. Never print a key, never commit a key, never expose a key to the browser bundle. 134. Clearance is a self reported indicator, shown in the UI as "clearance intelligence," never as "verified." The real check is the hiring client FSO through DISS at onboarding. State this once where clearance appears. 14 15## Demo data (sales demo seed) 16The candidate pool in the demo org is SYNTHETIC generated data, not real people, and is labeled "Demo data" in the UI everywhere candidates appear (the entire pool, not only the External sourced leads). Clearance values are seeded self reported indicators on generated profiles. A live demo must never imply these are real cleared people; the real check is the customer FSO through DISS at onboarding, and once Galapagos loads their own bench the seeded fillers fall away. The deliberate seed shaping is documented and reproducible in `db/seed/demo_gapfillers.sql`: nine rare skill holders are set available and TS/SCI active so the three hardest staffing gaps have legitimate fillers. That lets the Win Impact feature show HIGH on the Candidates page while the Command Center still names the open gaps (NEED 10 Intelligence Analysts, 3 Data Scientists, 2 Cyber Architects), so the two screens tell one connected story. It moves the Command Center to roughly readiness 86 Watch instead of 59.75 At Risk. 17 18## Authentication and Accounts (Phase 2 decisions, locked) 19The auth module lives in `internal/modules/auth` with the pure crypto and RBAC primitives in 20`internal/platform/security`. It produces a verified (org_id, user_id, role) from a first party 21opaque server side session and feeds `app.current_org_id` only from that validated state, never a 22client header. The tenancy foundation (RunInTenantTx, WithOrg, the RLS contract) is reused, not 23rebuilt. These choices are settled and must not drift: 241. **Password KDF is PBKDF2 with HMAC SHA 256 (SP 800-132), never argon2 or bcrypt.** Those KDFs sit 25 outside the FIPS validated boundary; PBKDF2 is inside CMVP module #5247 under GOFIPS140=v1.0.0. 26 Iteration count is 600000 (OWASP 2024 floor). SP 800-132 directs maximizing iterations within 27 tolerable latency, so this deliberately exceeds the CAVP tested envelope (iteration count 1 to 28 10000, password length 8 to 64). That is a stronger choice, not a deviation: state it that way to a 29 FedRAMP assessor. Password input is capped at 64 characters to stay inside the tested length bound. 302. **A versioned credential pepper** (HMAC SHA 256 of the password under a server held key, applied 31 before PBKDF2, stays in boundary) is stored as a per credential `pepper_version` so the pepper can 32 rotate without a flag day. TOTP secrets are AES 256 GCM encrypted at rest with a `key_version` so 33 the KEK can rotate too. 343. **MFA is mandatory TOTP** (RFC 6238, pinned to HMAC SHA 256 end to end, 32 byte secret, strictly 35 monotonic replay guard). TOTP is implemented in house on the standard library (crypto/hmac) rather 36 than a third party library, so every primitive stays provably inside the validated module and 37 there is no external crypto to re verify under fips140=on. No code path yields an active session 38 with MFA unsatisfied. 394. **Sessions are opaque and server side** (32 random bytes, stored only as a SHA 256 hash), in a 40 `__Host-` cookie (HttpOnly, Secure, SameSite Strict), instantly revocable, two stage (pre MFA then 41 active). Timeouts are fixed NIST values, 15 minutes idle and 12 hours absolute, computed and 42 compared by the database clock, not per org configurable in this phase. 435. **Identity is one human, one account, one org.** Email is globally unique (a functional unique 44 index on lower(email)); login resolves the user by global email before the org GUC is set, through 45 a SECURITY DEFINER cross org lookup. Multi org access for one human is a future membership table 46 refactor, not a Phase 2 capability. 476. **Org creation is provisioning plus invites only, no public self serve signup.** The first org and 48 owner are created by the migrator role `provision-org` CLI calling a migrator only SECURITY DEFINER 49 function; everyone else joins by an authority bounded invite. Invite and recovery link delivery is 50 manual at pilot (the endpoint returns the one time link, the owner delivers it); there is no email 51 transport in this phase. 527. **Federated SSO** (OIDC Login.gov, Entra Gov, SAML, WebAuthn and PIV CAC) and public forgot 53 password are deferred to sub phase 2.9. The seam is `internal/platform/idp`, which does not exist 54 yet. The five federal auth libraries are not added to go.mod in this phase. 55 **DO NOT put SSO in `internal/platform/identity`.** That name is already taken by a working 56 package that does something unrelated: it seeds an organization and its users from the control 57 plane into a tenant database so the tenant's business foreign keys (`requirements.created_by`, 58 `slate_members.decided_by` and the rest) resolve against local rows. This file claimed identity 59 was the SSO seam until 3 August 2026; it never was, and the claim was copied onward into the 60 owner's manual before anyone checked it. 618. **The dev X-Org-ID header resolver is removed** via a build tag split so it cannot compile into a 62 production binary, and is additionally hard rejected by config validation in production. 63 64## Products 65- **missionMATCH**: workforce intelligence ("who can support this mission today?") 66- **slateMATCH**: proposal staffing ("who belongs on the proposal candidate slate?") 67- **screenMATCH**: single-candidate qualification ("is this candidate qualified for this requirement?") = `POST /match` 68 69## Language & stack (Go — chosen for cloud portability + the cleanest federal FIPS story) 70- **Backend: Go 1.26+** — compiled, memory-safe, single static binary, native FIPS 140-3. 71- **HTTP**: `chi` router (idiomatic, std-lib-compatible `net/http`). Thin handlers; logic in services. 72- **DB**: PostgreSQL 16 + **pgvector** (HNSW). Access via **`pgx/v5`** (`pgxpool`); typed SQL via **`sqlc`** (compile-checked, no heavy ORM). `pgvector-go` for vector types/ops. 73- **Migrations**: a single tool (pinned in STACK_DECISIONS.md — `goose` or `golang-migrate`); migrations are the ONLY way to change schema. 74- **Multi-tenancy**: Postgres Row-Level Security (pool model) — see rules below. 75- **Skills**: ontology (taxonomy + embeddings + adjacency) in Postgres/pgvector. 76- **Search**: hybrid `tsvector` full-text + `pgvector` HNSW fused with **Reciprocal Rank Fusion (RRF)**, in SQL. 77- **Storage**: S3-compatible behind a Go interface (MinIO local; S3/GovCloud or Azure Blob in cloud). 78- **Parsing/embeddings**: behind a **provider interface** — managed FedRAMP endpoint (AWS Bedrock OR Azure OpenAI) OR self-hosted vLLM; cleared resumes are CUI, so production self-hosts. The core Go app never depends on a native ML stack — it calls the provider over HTTP. 79- **Frontend**: Vite + React 18 + TypeScript + TanStack Query + React Router + Tailwind + shadcn/ui + Recharts. 80 81## CLOUD-PORTABILITY MANDATE (non-negotiable — the founder's explicit requirement) 82The platform MUST run on **both AWS GovCloud and Azure Government** with **no single-vendor lock-in.** 83- Everything cloud-specific lives behind an interface: object storage, the AI/embedding provider, secrets, identity. Choosing a cloud is **configuration**, not code. 84- DB is portable managed Postgres+pgvector on either cloud (AWS RDS for PostgreSQL ↔ Azure Database for PostgreSQL Flexible Server). 85- Deploy as **containers + Terraform IaC** targeting both clouds; SBOM-at-build; FIPS-validated crypto. 86- Do NOT adopt an Azure-only or AWS-only primitive in the core path. If a cloud-specific feature is used, it is isolated behind a port/adapter with the other cloud's adapter present. 87 88## "Don't blindly build" rule (founder directive) 89Do NOT rely on stale patterns for Go specifics. Where the correct approach is non-obvious or 90version-sensitive — **the FIPS 140-3 module, pgx RLS-with-a-pool, pgvector HNSW DDL/queries, 91sqlc + pgvector type overrides, WebAuthn/OIDC/SAML/PIV-CAC libraries, both-cloud managed-Postgres 92support** — follow **docs/STACK_DECISIONS.md** (research-backed, source-cited, with verified minimal 93patterns). If something there is missing or uncertain, research it with live sources before coding it. 94 95## Non-negotiable engineering rules 961. **Multi-tenancy**: every tenant-scoped table has `organization_id`. Enforce with Postgres RLS 97 (`USING` + `WITH CHECK`) and `ALTER TABLE ... FORCE ROW LEVEL SECURITY`. The app sets 98 `SET LOCAL app.current_org_id` **per request transaction on the same pooled connection** 99 (the pgx-pool gotcha — see STACK_DECISIONS.md) from the validated session. Never trust a 100 client-supplied `organization_id`. No context set ⇒ **zero rows** (fail safe). The DB role the 101 app uses is non-superuser, `NOBYPASSRLS`; a separate migrator role has `BYPASSRLS`. 1022. Composite indexes lead with `organization_id` on every tenant table. 1033. **Audit logging**: a separate append-only `audit_logs` table OUTSIDE RLS. Log logins, record 104 create/update/delete, exports, permission changes — with actor/entity/old/new/ip/ua. Never UPDATE/DELETE it in app code. 1054. **PII/CUI**: clearance data and cleared resumes are sensitive. Never log PII in app logs. 106 Resume/RFP parsing goes through the provider interface (managed for synthetic demo, self-hosted vLLM for production CUI). 1075. **Security baseline (NIST 800-171 Rev 2 aligned)**: RBAC, MFA, AES-256 at rest, TLS 1.2+, 108 session/idle timeout, password policy, export logging, consent tracking. Build with the native 109 Go FIPS 140-3 module enabled (see STACK_DECISIONS.md) so crypto is validated from day one. 1106. **API-first**. Endpoints include `GET /candidates`, `GET /requirements`, `POST /match`, 111 `POST /slates/generate`, `GET /clearance-status`, `GET /proposal-readiness`. 112 113## Responsible AI rules (this is an Automated Employment Decision Tool) 1141. Every match score is **explainable**: per-component breakdown + human-readable rationale + gap summary + a recordable decision trace. 1152. **Human-in-the-loop**: humans approve/reject every slate member. Never auto-reject. 1163. **Demographic/EEO data** lives in a separate module, is privacy-protected, and is **NEVER** an 117 input to matching (no protected attributes or close proxies as features). The matching/search code must never reference the EEO table. 1184. Provide **adverse-impact reporting** (selection rates + four-fifths/80% ratios) so customers can run NYC LL144 / OFCCP audits. 1195. Maintain a model card / scoring-methodology doc; align to NIST AI RMF and ISO/IEC 42001. 120 The platform PROVIDES the data for customers' bias audits; it does not itself constitute one, and vendor tooling does not transfer the employer's liability. 121 122## Matching engine (fixed weights — do NOT change without explicit instruction) 123Match Score = Clearance*0.25 + Skills*0.25 + Certifications*0.15 + CustomerExperience*0.15 124 + Experience*0.10 + LocationAvailability*0.10 (total 100) 125- **Clearance**: exact OR higher than required = 100%; lower / expired / unknown = 0% 126 (TS/SCI satisfies Secret; Secret does NOT satisfy TS/SCI — encode the hierarchy). 127- **Skills**: 100% of required met = full; 80–99% = partial; below 80% = reduced. Skill matching 128 uses **exact match first, then semantic similarity** (embeddings) for synonyms/adjacent skills; 129 always record which candidate skill matched which required skill and the similarity. 130- **Bands**: Green (Proposal Ready) 90+, Yellow (Potential) 75–89, Red (Recruiting Required) <75. 131- The engine is a **pure, deterministic Go package** — no DB, no I/O, `skill_matcher` injected. 132 **All scoring math uses `shopspring/decimal`, never `float64`** (bit-stable determinism for the 133 AEDT/compliance asset). Exhaustively unit-tested with golden + property tests; lint with 134 `go-exhaustive`/`nilaway`/`errcheck`. LLM ranking is a FUTURE layer ON TOP, never a replacement. 135 136## Conventions 137- Package layout: `internal/platform/<area>` for cross-cutting (config, db, tenant, security, audit, 138 storage, embeddings); `internal/modules/<name>` per domain with `handler.go`, `service.go`, 139 `repo.go` (sqlc-backed), `dto.go`. Wire HTTP routes in one place. `cmd/api/main.go` is the entrypoint. 140- Errors are values, wrapped with `%w`; no panics in request paths. Context-aware. `gofmt`/`go vet`/ 141 `golangci-lint` clean. Every feature ships with tests; the pure logic must pass without a DB. 142- Schema changes via migrations only. SQL is authored in `.sql` and compiled by `sqlc`. 143 144## Brand (frontend) 145Deep Navy #0F2744 (primary), Steel Blue #2E5EAA (secondary), Mission Gold #D4A017 (accent), 146Light Gray #F4F6F8 (neutral). App shell: left sidebar nav, top stat cards, dashboard charts. 147