5. Intake, search, reporting, and operations
Map the surrounding services. Understand what enters the app, what stays derived, and what a download proves.
Intake preserves source evidence
- An authorized role provides two attested synthetic pipe-delimited files for closed/suspended and rejected samples.
- The parser expects exactly 42 columns. It supports quoted pipes, doubled quotes, and an optional exact-order header row.
- It accepts supported Negative review-number/action shapes and rejects individual records. It keeps file/line metadata and raw lineage.
- Accepted records begin without invented verified household, computation, final result, or examiner outcome.
- Intake binds the dated policy and captures the examiner received copy. Business identity distinguishes new intake from refresh.
- Refresh preserves saved UUID and existing algorithm/policy bindings. Dropped reviews cannot be refreshed. Review refresh guards before approving overwrite behavior.
Source: parser, intake command, route, and 42-column field reference. The synthetic attestation checks a marker. It cannot establish that file content is actually anonymous. Production needs a separate approved ingestion contract.
Queues, catalog, and search
| View | Read path | Design consequence |
|---|---|---|
| Inbox | Scoped SQL index pages and recipient inbox events. Visible refresh is periodic. | It is not a websocket/live collaboration service. Seen, flagged, and read-version are separate state. |
| Reviews catalog | Indexed scope, folders and pagination. | Avoid fetching every complete snapshot for a small list. |
| Header search | Fast suggestions and full-result navigation. | A suggestion list is not a complete report. |
| Expanded search | Field catalog, typed filters/ranges, sorting, and selected display paths. | Use index data when possible. Join current snapshot fields only when needed. |
| Reports | Saved report projections and release eligibility. | Projection rebuilds must preserve approved totals. |
| Exports | Sample-month selection and current snapshot eligibility recheck. | Statistics gets FNS fields. Supervisors/managers get EPP fields. Download roles differ from report roles. |
Reporting gates and integration limits
Program Error Summary includes manager-released non-drops. Transmittal eligibility also includes manager-approved drops. The FNS output is a current-template FNS-245 field TSV. It is not a certified federal wire format or proof of portal acceptance. EPP output contains a small verified identity mapping and does not write to the external Access table.
The demo does not implement automatic email delivery, memo delivery receipts, approved notice generation, print queues, or portal submission. A saved outbound memo status is an internal fact in this demo. Production needs evidence of actual delivery before a response clock depends on it.
Operations and reproducibility
| Concern | Current mechanism | Production task |
|---|---|---|
| Migrations | Versioned SQL in drizzle and target-aware migration script. Current schema includes 0008_report_required. | Review migration compatibility, rehearsal, backups, rollback/forward recovery, and deployment approval. |
| Synthetic fixtures | Seed 42 by default, deterministic identities, sample months and as-of day. | Keep fixtures separate from approved-data environments. A seeded baseline is not real agency volume. |
| Projection backfill | Rebuild report index from stored review data. | Verify totals before and after. Make rebuild observable and restartable. |
| Performance | Data/compute budgets plus browser cold-entry/navigation journeys. | Measure agreed volume on approved infrastructure and a representative staff network. |
| CI | Typecheck, lint, format, migrations, seed, unit and DB integration tests with temporary PostgreSQL 18. | Add protected release pipelines, build/browser gates, dependency review and managed secrets. |
| Wiki | Maintained HTML, local navigation, compiled article and source allowlist assets. | Review public documentation/source exposure for the real service. This demo serves docs without staff review-data calls. |
The README includes production-target commands because the hosted synthetic demo has a deployment target. The word production in a script does not certify operational readiness. Do not run seed/reset, migration, or pruning against an agency database as a learning exercise.
Safe checks to understand
bun run docs:generate bun test src/features/docs/compile.test.ts bun run typecheck bun run lint bun run fmt:check With an approved disposable test database only: QC_DB_INTEGRATION=1 bun test With an isolated test server and synthetic fixtures only: bun run test:e2e bun run test:perf
Read test configuration first. Browser tests start a production build and some journeys edit fixtures. Database integration tests create and clean isolated records. Use a test target approved for those writes. The performance guide explains simulated versus real network measurements.
Exercise and answer key
Search returns 50 rows fast. A report total is correct. A TSV downloads. Which of these proves that 500 staff can submit federally accepted files at month end?
Answer
None proves that claim. The checks answer separate questions: scoped query behavior, projection arithmetic, and export generation. Month-end concurrency needs representative load and recovery tests. Federal acceptance needs a receiving-system contract and observed acceptance receipts. Staff count 500 is a hypothetical test input, not a measured limit.
Next: lesson 6. Deep reading: import, reports, performance.