Janady13/missionmatch / docs/superpowers/specs/2026-07-20-recruitmatch-design.md

1# recruitMATCH and org branding: design 2 3Status: proposed, awaiting review 4Date: 2026 07 20 5Author: design session with Joseph 6Branch: feature/aioe-upgrade 7 8## 1. Purpose 9 10Add **recruitMATCH**, a fourth product tool alongside missionMATCH, screenMATCH and slateMATCH, 11giving recruiters an operational dashboard over work the platform already performs. Add 12**per organization branding** so the application white labels for every client that buys it. 13 14FG Talent Partners is the first client of missionMATCH. It is not the only client. Nothing in this 15design may be FG specific. FG is a row in `organizations` and nothing more. 16 17## 2. Non goals 18 19These are explicitly out of scope. Each would be its own design. 20 211. No applicant tracking spine. No client account entity, job requisition entity, hiring manager, 22 interview, offer, placement, bill rate, pay rate, invoice, recruiter activity log, or task and 23 reminder tables. Verified absent across all 47 migrations and against the live schema. 242. No change to the scoring engine. `engine.ModelVersion` stays `v1.4.0` and the six weights are 25 untouched. 263. No per tenant database routing. That work lives unmerged on `per-tenant-routing` and is a 27 separate project. Tenancy here is the existing shared database plus forced RLS. 284. No orchestration layer. Parked. 295. No change to the EEO boundary. recruitMATCH must never read the `eeo` schema. 30 31## 3. What a tool is in this codebase 32 33Verified from the existing three. A tool is a repeatable structure, not a concept. 34 35Frontend 36* `frontend/src/tools/<tool>/brand.ts` exporting `{key, name, tagline, accent, basePath}` 37* `frontend/src/tools/<tool>/api.ts` with `const NS = '/<tool>'` and a client object 38* `frontend/src/tools/<tool>/queries.ts` with hooks keyed `['<tool>', resource, ...params]` 39* `frontend/src/tools/<tool>/*.tsx` screens, named exports, no default export 40* one entry in the `TOOLS` array in `frontend/src/components/AppShell.tsx` 41* one accent token in the `@theme` block of `frontend/src/index.css` 42 43Backend 44* `internal/modules/<tool>/{dto,service,service_queries,handler}.go` 45* `r.Route("/<tool>", handler.Routes)` in `cmd/api/main.go` 46 47## 4. How the tools commingle, and how recruitMATCH joins 48 49screenMATCH and slateMATCH are not parallel silos. They share one `*matching.Handler` instance, and 50`matching.ReadRoutes` is mounted under every tool prefix, so `/api/screenmatch/candidates` and 51`/api/slatematch/candidates` answer identically. 52 53The deeper join is through shared tables: 54 55``` 56screenMATCH scores a candidate writes candidate_evaluations 57slateMATCH builds a slate writes slates and slate_members 58missionMATCH Command Center aggregates both into readiness 59recruitMATCH aggregates both into recruiting operations 60``` 61 62recruitMATCH joins the family two ways: 63 641. It mounts `matching.ReadRoutes` under `/recruitmatch`, exactly as the other three do. 652. It reads the same tables the other tools write. recruitMATCH is the outcome view of work performed 66 in screenMATCH and slateMATCH. It introduces no private tables. 67 68## 5. Data contract, panel by panel 69 70Every source below was verified against the migrations and the live schema. Panels with no source 71render an explicit empty state that names the missing feed. They never render a fabricated number. 72 73### Backed by real data 74 75| Panel | Source | 76|---|---| 77| Active jobs | `requirements` where parent `opportunities.status = 'open'` or `opportunity_id is null` | 78| New candidates | `candidates.created_at` inside the window | 79| Submissions | `slate_members.created_at` inside the window | 80| Screened | `candidate_evaluations.evaluated_at` inside the window | 81| Band mix, green yellow red | `candidate_evaluations.band` | 82| Approvals and rejections | `slate_members.decision` with `decided_at` | 83| Decision velocity | `slate_members.decided_at` minus `slate_members.created_at` | 84| Recruiter attribution | `slate_members.decided_by` and `candidate_evaluations.evaluated_by` joined to `users` | 85| Top active jobs | `requirements` left joined to a count of `slate_members` | 86| Clearance breakdown | `candidates.clearance_level` joined to `clearance_levels` | 87| Alerts feed | existing `GET /api/alerts`, populated by the scheduled `alert-sweep` timer | 88| Recommended actions | existing `GET /api/recommendations/proactive`, populated by `staffing-proactive-sync` | 89 90### Not backed, rendered as an explicit empty state 91 92| Panel | Why | 93|---|---| 94| Interviews | no interview entity exists | 95| Offers | no offer entity exists | 96| Placements | no placement entity. `vendor_submissions.status = 'placed'` exists but is keyed by vendor, so a recruiter placement cannot be recorded | 97| Revenue | no bill rate, pay rate, margin or invoice anywhere in the schema | 98| Average time to fill | `requirements` has no fill date. Migration 0039 seeds a flat hazard prior and feeds from nothing | 99| Candidate source breakdown | `candidates.source` is `CHECK (seed, external)`. Job board attribution cannot be expressed | 100| Activity trend, placement series | the other three series are real. The placement series has no source | 101 102### Two deliberate substitutions 103 104The mockup shows an Upcoming Tasks panel and an AI Insight panel. Neither has a data source. Both 105are replaced with feeds that are real and already accumulating behind no interface today: 106 107* Upcoming Tasks becomes the **Alerts** feed from `GET /api/alerts`. 108* AI Insight becomes **Recommended actions** from `GET /api/recommendations/proactive`. 109 110This trades two invented panels for two panels with live scheduled data. 111 112## 6. Backend design 113 114New module `internal/modules/recruitmatch`, following the Command Center vertical slice, which is 115the proven aggregation pattern here. 116 117``` 118dto.go View plus nested panel types. Every money and percentage value is a string. 119service.go Service{db, audit, clock}. One entry point: 120 RecruiterDashboard(ctx context.Context, asOf time.Time) (View, error) 121service_queries.go buildTemps plus SQL panel builders. SQL returns counts only. 122derive.go pure banding, classification and copy. No ctx, no tx, DB free tests. 123handler.go Routes(r chi.Router), as_of parsing, error mapping. 124*_test.go pure tests against hand built View structs. 125``` 126 127Rules carried over from Command Center because they are load bearing: 128 1291. **One** `RunInTenantTx` for the whole request. 1302. **Keep the GUC assertion.** `buildTemps` refuses to aggregate when `app.current_org_id` is unset. 131 On a product serving many clients this is the difference between a bug and a cross tenant breach. 1323. TEMP tables prefixed `rm_`, all `ON COMMIT DROP`, so they can never collide with the `cc_` temps. 1334. SQL returns counts only. All banding happens in Go, importing `engine.BandGreenMin` and 134 `engine.BandYellowMin` rather than redeclaring thresholds. 1355. `as_of` is bound as `$1::date`. No `now()` and no `current_date` anywhere in the module, so a 136 fixed `as_of` produces byte identical output. 1376. All arithmetic uses `shopspring/decimal`. Percentages use a helper that guards a zero denominator. 1387. Do **not** copy the `upcomingOpportunities` shape from Command Center. It is a real N plus 1. 139 140### Routes 141 142```go 143r.Route("/recruitmatch", recruitH.Routes) 144``` 145 146| Method | Path | Capability | Notes | 147|---|---|---|---| 148| GET | `/api/recruitmatch/dashboard` | `CapCandidateRead` | optional `as_of` in `2006-01-02` | 149| GET | `/api/recruitmatch/candidates` | `CapCandidateRead` | shared `matching.ReadRoutes` | 150| GET | `/api/recruitmatch/requirements` | `CapCandidateRead` | shared `matching.ReadRoutes` | 151 152`CapCandidateRead` includes every role down to `viewer`, so the dashboard is visible to all members 153of an org. 154 155Alerts and recommendations stay at their existing flat paths. They are genuinely cross tool and 156aliasing them a fourth time would add registrations without adding meaning. 157 158### Error mapping 159 160Follow the Command Center handler: `tenant.ErrNoTenant` maps to 403, `ErrNoDatabase` maps to 503, 161anything else maps to 500 with a fixed body that never leaks a wrapped error. 162 163## 7. Frontend design 164 165New directory `frontend/src/tools/recruitmatch/` containing `brand.ts`, `api.ts`, `queries.ts` and 166`RecruiterDashboard.tsx`. 167 168* Accent: one new token in the `@theme` block of `src/index.css`, joining screenMATCH teal `#14b8a6` 169 and slateMATCH violet `#8b5cf6`. 170* `TOOLS` gains a fourth entry with `basePath: '/recruit'` and a `match` covering that prefix. 171* Query keys follow `['recruitmatch', resource, ...params]`. 172* Every decimal arrives as a string and is converted with `num()` from `lib/format.ts`. 173* Reuse `Panel`, `Stat`, `Bar`, `Badge`, `Gauge` and `ToolHeader`. Do not invent card markup. 174* Dynamic colors are `var(--color-*)` inline. Static colors are Tailwind classes. 175* `tabular-nums` on every number. 176* The screen owns no outer padding. `AppShell` main already applies it. 177 178**Handle the error state.** `CommandCenter.tsx` destructures without `isError`, so a failed fetch 179leaves its loading panel on screen forever. Copy the pattern in `screens/Requirements.tsx` instead. 180 181Charts: recharts is already a dependency but is used in exactly one file. The dominant idiom is hand 182built SVG. Use `Bar` and `Gauge` for meters and reach for recharts only for the multi series activity 183trend, matching the styling in `components/WorkforceDNA.tsx`. 184 185## 8. Org branding, platform scope 186 187This is platform work, not recruitMATCH work. All four tools inherit it. 188 189**Migration 0046** adds to `organizations`: `display_name text`, `logo bytea`, `logo_mime text`, 190`accent_color text`. RLS policy `org_self_select` already scopes reads to the GUC. The existing 191column grant is deliberately narrow at `UPDATE (name)`, so widen it to exactly the new columns and 192leave `status` locked so a tenant cannot un suspend itself. 193 194**Extend `SessionInfo`** with the org display name and a flag indicating a logo exists. `AuthProvider` 195already fetches `/api/auth/session` once on mount and `AppShell` already consumes the principal, so 196branding arrives with no extra request and no new fetch plumbing. 197 198**Serve the logo** from `GET /api/org/logo`, session gated, returning the current org bytes with the 199stored content type. Writes are gated by `CapOrgSettings`, which is owner only. Upload UI goes in 200`screens/Settings.tsx` beside the existing team panel. 201 202**`AppShell` renders** the org mark in the sidebar header, falling back to the missionMATCH mark when 203an org has not uploaded one, which is every org on its first day. 204 205Storage decision: keep logo bytes in Postgres for v1. Logos are tens of kilobytes, one row per 206tenant, and the bytes inherit RLS isolation automatically. Wiring object storage into the API would 207mean building the AWS adapter that does not exist yet, for a few kilobytes per client. The `Storer` 208interface in `internal/platform/storage` remains available if this ever outgrows a column. 209 210## 9. Multi tenancy requirements 211 212Non negotiable, and the reason for the GUC assertion above. 213 2141. No org identifier ever appears in a handler signature. Org is ambient in context and reaches 215 Postgres only through `RunInTenantTx`. 2162. No FG string, FG asset, or FG conditional anywhere in the codebase. 2173. Every panel must render correctly for an org with zero rows. A new client sees zeros and named 218 empty states, never a crash, a NaN, or a fabricated figure. 2194. Recruiter attribution derives from `users` in the tenant, so it works for a one recruiter shop and 220 a twenty recruiter shop without configuration. 221 222## 10. Testing 223 224* Pure unit tests for `derive.go` against hand built `View` structs, no database, mirroring 225 `commandcenter/executive_test.go`. 226* A test asserting a zero data org produces a complete `View` with zeros and no panic. This is the 227 new client case and it is the one most likely to regress. 228* An integration test under the `integration` build tag proving two orgs see disjoint dashboards. 229 Note that the integration suite exits 0 silently when `MM_APP_DSN` and `MM_MIGRATOR_DSN` are unset, 230 so a green run does not prove it executed. Confirm the DSNs are exported. 231* `make build-test-gates` must pass, including gofmt, vet, the backdoor check, the FIPS check and the 232 frontend lint and build. 233 234## 11. Deployment notes 235 236Production is behind this branch and that must be reconciled before shipping. 237 238* Live goose version is 42. This branch is at 45. Migrations 0043, 0044 and 0045 are not applied, so 239 `outcome_events`, `aioe_weight_profiles` and `term_expansions` do not exist in production. 240* The `mm-api` binary and the frontend bundle in production were both built on July 1. 241* Deployment is manual. CI runs gates and never deploys. 242 243Sequence: apply 0043 through 0046, rebuild and deploy the binary, rebuild and deploy the frontend. 244 245## 12. Open questions 246 2471. The tool name is recruitMATCH and the base path is `/recruit`. Confirm both. 2482. Accent color for the fourth tool. 2493. Whether `accent_color` in org branding should actually theme the shell, or only be stored for 250 later. Storing it is cheap. Applying it interacts with the fixed tool accents and needs a rule. 2514. The activity trend window. The mockup shows seven days. 252 253## 13. Related findings, out of scope but recorded 254 255Surfaced during the scan. Each deserves its own ticket. 256 2571. `docs/MODEL_CARD.md` documents `v1.1.0` while the engine is `v1.4.0`, missing both band caps and 258 the compartment check. For a product whose central claim is auditability this is the highest 259 severity item found. 2602. `ontology_crosswalk` is queried by a live code path but has no writer anywhere, so `SkillGapBridge` 261 silently under returns. 2623. `internal/platform/federated` and `dp_budget_ledger` have zero importers. Dead code. 2634. `/api/opportunities`, `/api/awards` and `/api/wages` have no capability gate at all. 2645. `/metrics` is unauthenticated and outside the rate limiter. 2656. Several buttons render as working features with no handler attached, in `CommandCenter.tsx` and 266 `CandidateEvaluation.tsx`. 2677. `users.last_login_at` is never written, though `login_attempts` records the successes. 268