# Knowledge graph index

_Generated by `kg.mjs index` — do not edit. Start with [README](README.md)._

179 nodes.

## entity (47)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [document](nodes/document.md) | A scannable paper form (identified by doc_code) whose page PDF, page count, row density and record type drive field design, test cases, VIPP print and SRL. | 58 | 5 | entity, forms |
| [field](nodes/field.md) | One OMR field drawn on a document page: its bubble grid (xy clicks), content (allowed characters), ARL position in the scan record, skip pattern and clip box. | 47 | 3 | entity, forms |
| [scan-pgm-document](nodes/scan-pgm-document.md) | Join of a document (doc code) into a scan program - the unit that moves through the SPS and PV task stages, gets an SRL, VIPP test decks and test-admin eligibility. | 41 | 4 | entity, scan-program |
| [scan-pgm](nodes/scan-pgm.md) | A scan program - one customer program's scanning configuration under an account (program name, legacy SSN, cost center, row density, SRL lock flag, image app); the parent of its documents, test administrations and SRL anchors. | 34 | 5 | entity, scan-program |
| [vipp-request](nodes/vipp-request.md) | One file sent to VIPP for rendering — a document test deck, a print-run label sheet or print list, or the health check — tracked from pending (P) to PDF returned (C). | 32 | 5 | entity, print-vipp, vipp |
| [task-approval](nodes/task-approval.md) | One stage reached by a scan program document - (scan_pgm_document, task, user) plus a notes JSON that carries the VIPP requests staged for Tuesday Print; the highest row per task group is the document's current stage. | 31 | 4 | entity, workflow |
| [test-admin](nodes/test-admin.md) | A test administration inside a scan program - admin code, processing SSN and per-system codes (PASS, ADAM) that tie PSAES documents to a customer administration; exactly one active default per program, which the processing SSN resolves through. | 30 | 5 | entity, scan-program, integration-key |
| [content](nodes/content.md) | A named OMR character set (e.g. 0-9, A-Z, 01-12, litho) that says which character each bubble of a field encodes; the master list fields pick from. | 28 | 2 | entity, forms |
| [test-case](nodes/test-case.md) | A user's test-data set for one document (one row per document+user), optionally tied to a scan-program document and to the uploaded source file in S3. | 27 | 6 | entity, test-cases |
| [user](nodes/user.md) | A PSAES application user (psaes."user") - username, email, full name, 5-digit client id, last login, inactive flag, plus legacy password columns no code authenticates against; the userId the UI sends with workflow and job calls. | 26 | 3 | entity, users |
| [document-pgm-ssn](nodes/document-pgm-ssn.md) | Per-document program/session settings — contract, program-session code (pgm_ssn), alternate description, barcode check-digit method and preid/security barcode start numbers. | 24 | 2 | entity, forms |
| [account](nodes/account.md) | A customer account / contract (e.g. a state program) that owns scan programs - name, unique program number and a 2-5 character account code that matches the customer code other systems (ADAM, PASS) use. | 23 | 3 | entity, scan-program, integration-key |
| [srl-anchor](nodes/srl-anchor.md) | A scan program's saved SRL anchor layout for one record type (labels at byte positions plus flow, name-convert and barcode rules); locked together with the scan program. | 21 | 4 | entity, print-vipp, srl |
| [srl-document](nodes/srl-document.md) | The generated SRL of one scan-program document — srl_json with assigned/unassigned/multipage/editclip/notOnField anchors and the unformatted text layout; the source of the PASS extract. | 21 | 3 | entity, print-vipp, srl |
| [test-admin-document](nodes/test-admin-document.md) | Doc-code eligibility - which scan program documents a test administration covers; one row per covered document, no row means not covered. | 21 | 3 | entity, scan-program |
| [print-request](nodes/print-request.md) | A returned VIPP PDF queued for physical printing, with page/signature/cost estimates; swept into a print run by startPrintRun. | 19 | 5 | entity, print-vipp, print |
| [test-case-list-field](nodes/test-case-list-field.md) | The value one field gets in one test record, plus the erasure-analysis (EA12/28/44/99) light-mark values and clip text for that field. | 19 | 3 | entity, test-cases |
| [test-case-list](nodes/test-case-list.md) | One test record (one printed/scanned sheet set) within a test case, named after its pattern (e.g. "0-9 ALL 7(10000001)", "QA") or the uploaded testCaseId. | 19 | 3 | entity, test-cases |
| [task](nodes/task.md) | One workflow stage in a task group (e.g. SPS-PDF Awaiting PDF, SPS-SRL SRL Process, SPS-VIPP VIPP Test Deck, SPS-TUES Tuesday Print, PV-VIPP), ordered by sequence_nbr; seeded reference data. | 18 | 2 | entity, workflow, reference-data |
| [user-alert](nodes/user-alert.md) | An in-app notification for a user (alert_desc + acknowledged flag) raised when a background job finishes - test case generation, CSV test-data processing, VIPP file returned - with the long text in user_alert_detail. | 18 | 3 | entity, users, notifications |
| [arl](nodes/arl.md) | One node of a document's parsed ARL tree — a group or leaf field with byte position, length and valid values (e.g. "0=Not Gridded", "Force ... In Scan"). | 17 | 3 | entity, print-vipp, arl |
| [test-admin-system-code](nodes/test-admin-system-code.md) | A test administration's code in another system - one row per (test admin, system), today PASS and ADAM - replacing the old pass_admin_code / adam_admin_code columns. | 16 | 2 | entity, scan-program, integration-key |
| [health-check](nodes/health-check.md) | Liveness record per dependency (PSAES database, VIPP server) with last request / success timestamps shown on the admin page. | 13 | 1 | entity, print-vipp, admin |
| [user-alert-detail](nodes/user-alert-detail.md) | The long text body of a user alert (job run summary, created records, VIPP return message); one per alert in practice. | 13 | 2 | entity, users, notifications |
| [srl-baseline](nodes/srl-baseline.md) | Seeded default SRL layout per record type (01, 17, 99) that a scan program's anchor layout starts from. | 12 | 1 | entity, print-vipp, srl, reference |
| [task-group](nodes/task-group.md) | A workflow track for scan program documents - seeded 'SPS Scan Program Testing' and 'PV Testing' - each an ordered list of tasks (stages); carries an unused role_id. | 12 | 3 | entity, workflow, reference-data |
| [arl-file](nodes/arl-file.md) | The uploaded ARL file of a document (one per document) — S3 location, file name and computed record length (lrecl). | 11 | 3 | entity, print-vipp, arl |
| [print-run](nodes/print-run.md) | A batch of print requests sent to the print shop together, with its VIPP-rendered label sheet, print-list sheet and the final zip. | 11 | 3 | entity, print-vipp, print |
| [vipp-request-test-case-name](nodes/vipp-request-test-case-name.md) | Immutable snapshot of which test cases (one row per VIPP record) went into a VIPP request; the source of truth for print pages, signatures, cost and label quantity (PSAES-513). | 11 | 3 | entity, print-vipp, vipp |
| [content-test-case](nodes/content-test-case.md) | A canned bubbling pattern for one content (e.g. "0-9 ALL 7", "A stripe"); the generator makes one test case per pattern of the richest content on the form. | 10 | 2 | entity, test-cases |
| [image-app](nodes/image-app.md) | A named imaging application (the downstream scanning/image system a scan program is processed in); scan programs link to one, and the Scan Test screen offers the image apps an account already uses. | 10 | 1 | entity, scan-program, reference-data |
| [role](nodes/role.md) | Seeded role names (god, admin, adminView, docDescr, owatanna, SPS, PV) from the original design; only task_group.role_id references them and no backend code reads the table. | 10 | 1 | entity, users, reference-data |
| [scan-pgm-task](nodes/scan-pgm-task.md) | Read-only Postgres VIEW psaes.scan_pgm_task - per scan program document and task group, the furthest stage reached (max task sequence) with doc code and approval audit columns; drives the Scan Test stage grid. | 10 | 4 | entity, scan-program, view |
| [task-approval-history](nodes/task-approval-history.md) | Archive of task_approval rows removed by a workflow revert (today only the SRL unlock), grouped by archive_event_id, so the VIPP notes can be carried back onto the new row when the document returns to the VIPP Test Deck stage. | 8 | 4 | entity, workflow, audit |
| [clip-rule](nodes/clip-rule.md) | Padding rule (cells added on each side of the bubble box) per field kind, used to compute a field's automatic clip box; tunable without a release. | 7 | 1 | entity, forms, clip |
| [user-role](nodes/user-role.md) | Join table user -> role from the original schema; no repository or service reads or writes it, and its V1 seed inserts are broken so it is likely empty. | 6 | 3 | entity, users |
| [wfm](nodes/wfm.md) | Inbound workflow-manager message (uuid, action, JSON payload, status R); stored by /api/wfm/start-process and never processed. | 6 | 1 | entity, print-vipp, wfm, dead |
| [exception-log](nodes/exception-log.md) | One row per exception handled by GlobalExceptionHandler (trace id, exception class, HTTP status, path, method, optional userId/documentId query params, first 15 stack frames as JSONB), written asynchronously and purged after 90 days. | 5 | 1 | entity, observability |
| [status-group](nodes/status-group.md) | Dead status-engine table: a named status group (e.g. gridDocument) whose JSON definition lists ordered processes and their prerequisites. | 5 | 2 | entity, print-vipp, status, dead |
| [rpt-proj-cost](nodes/rpt-proj-cost.md) | Project-cost report rows loaded wholesale from an Oracle project-cost CSV export (the "MK report"); truncated and reloaded on every upload. | 4 | 1 | entity, print-vipp, admin, report |
| [status-entity](nodes/status-entity.md) | Dead status-engine table: binds a document to a status group and its current status_flags row. | 4 | 4 | entity, print-vipp, status, dead |
| [status-process](nodes/status-process.md) | Dead status-engine table: one process (step) of a status group with its flag position and ready/completed Y/N/_ flag masks. | 4 | 2 | entity, print-vipp, status, dead |
| [status-flags](nodes/status-flags.md) | Dead status-engine table: a Y/N/_ flag string recording which status processes an entity has completed. | 3 | 1 | entity, print-vipp, status, dead |
| [vipp-grid-type](nodes/vipp-grid-type.md) | Seeded reference list of VIPP grid-type tokens (FillGrid, Gridtxt, Litho, LithoTxt, Single, Single12/28/44, TxtOnly) describing how each field slug is rendered; documentation only. | 3 | 1 | entity, print-vipp, vipp, reference |
| [status-tsx](nodes/status-tsx.md) | Dead status-engine table: a transaction log row recording that a status entity completed a status process. | 2 | 3 | entity, print-vipp, status, dead |
| [test-case-errors](nodes/test-case-errors.md) | Unused table meant to hold per-record errors of a test-case build; nothing reads or writes it (no repository). | 1 | 2 | entity, test-cases |
| [vipp-doc-type](nodes/vipp-doc-type.md) | Seeded reference list of VIPP DocType column values (QA, 6x6Grid, 6x8Grid, Cutsheet, Booklet) with their meaning; documentation only, never read by code. | 1 | 1 | entity, print-vipp, vipp, reference |

## module (22)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [scan-workflow-service](nodes/scan-workflow-service.md) | Scan test workflow engine - moves scan program documents through the SPS / PV task stages (complete, remove, stage VIPP PDF for print, Tuesday Print, request VIPP PDF), deletes program documents, and archives/restores task approvals around an SRL unlock. | 45 | 23 | module, workflow |
| [vipp-service](nodes/vipp-service.md) | Builds VIPP CSV data files from a document's test cases, drops them on S3 for the VIPP print server, and records the PDFs VIPP sends back (vipp_request lifecycle P -> C). | 41 | 26 | print-vipp, vipp |
| [srl](nodes/srl.md) | SRL (scan record layout) engine — per scan program anchor layouts by record type, per-document generated SRL JSON, the unformatted SRL text, and the lock that freezes the layout. | 29 | 14 | print-vipp, srl |
| [form-design](nodes/form-design.md) | Services behind form design — documents (incl. page-PDF upload), program/session settings, fields (with skip-pattern validation), contents and demo-page copy. | 28 | 20 | module, forms |
| [test-case-generation](nodes/test-case-generation.md) | Builds test data for a document — either system-generated bubbling patterns per content test case, or test records imported from an uploaded pipe-delimited (flat) file — and renders them back as flat records. | 28 | 19 | module, test-cases |
| [print-run-service](nodes/print-run-service.md) | Queues returned VIPP PDFs as print requests, batches them into a print run with VIPP-rendered label and print-list sheets, and zips everything plus a billing list for the Tuesday print shop. | 27 | 17 | print-vipp, print |
| [scan-program-service](nodes/scan-program-service.md) | Scan program setup - accounts (with account code), scan programs, adding documents to a program (find-or-create document, pgm-SSN row, start task approvals, default test-admin eligibility) and image apps. | 26 | 18 | module, scan-program |
| [csv-test-data](nodes/csv-test-data.md) | CSV round-trip of test data — download a document's test cases as an editable CSV (columns from SRL-assigned fields) and upload an edited CSV back into test case lists, including EA darkness rows and clip text. | 23 | 17 | module, test-cases |
| [psaes-backend](nodes/psaes-backend.md) | Spring Boot 4 / Java 17 service (esuite-psaes-backend) exposing every PSAES REST controller under /api - forms design, test cases, VIPP/print, scan programs and scan tests, users; PostgreSQL via JPA, files in S3; no request authentication. | 21 | 4 | module, api |
| [test-admin-service](nodes/test-admin-service.md) | Test administrations of a scan program - default admin lifecycle, admin code / processing SSN / system code validation and uniqueness, and doc-code eligibility (which documents each administration covers), plus account-code + admin-code resolution for integrations. | 20 | 13 | module, scan-program, integration-key |
| [litho-automation](nodes/litho-automation.md) | Plans and generates the litho (sheet serial-number) fields of a document — one per selected page, with ARL positions 8 bytes apart, honoring orientation, SRL anchors and manual edits. | 15 | 7 | module, forms, litho |
| [status-service](nodes/status-service.md) | Unused generic status-flag engine (status_group / status_process / status_flags / status_entity / status_tsx) meant to track a document's progress as a Y/N/_ flag string; superseded by scan-program task approvals. | 15 | 7 | print-vipp, status, dead |
| [field-clip](nodes/field-clip.md) | PSAES-491 clip boxes — computes each field's automatic image-clip rectangle from its bubbles and padding rules, and stores user-adjusted (manual) boxes clamped against neighbouring fields. | 14 | 3 | module, forms, clip |
| [arl-import](nodes/arl-import.md) | Uploads a document's unformatted ARL file to S3 and parses it into the arl tree (field name, position, length, valid values) that field design and SRL generation read. | 13 | 11 | print-vipp, arl |
| [user-alert-service](nodes/user-alert-service.md) | In-app user alerts - background jobs add an alert plus a detail text for a user; the UI lists them and acknowledges them. | 13 | 5 | module, users, notifications |
| [pass-extract](nodes/pass-extract.md) | Read-only extracts for the PASS system — the SRL layout of one document (units, items, scan field and intensity positions) and the list of doc codes with SRL status for an account/admin. | 12 | 12 | print-vipp, srl, extract |
| [test-data-validation](nodes/test-data-validation.md) | Pre-generation checks on uploaded test-data files (CSV or flat) — blocking error checks (content assigned, secondaryId, unique testCaseId, ids, docCode) and non-blocking warnings (blank-row cleaning, docCode mismatch, barcode check digits). | 12 | 3 | module, test-cases, validation |
| [user-service](nodes/user-service.md) | PSAES user maintenance - list (password-free projection), look up by username/email, add (generated client id and random bootstrap credential), update details, activate/deactivate, and record logins. | 10 | 4 | module, users |
| [exception-handling](nodes/exception-handling.md) | Cross-cutting error handling - PsaesBaseException hierarchy (~49 classes) mapped to HTTP status by GlobalExceptionHandler into a uniform ExceptionResponse with a per-request trace id (TraceIdFilter), every error persisted asynchronously to exception_log and purged daily. | 9 | 5 | module, cross-cutting, observability |
| [admin-service](nodes/admin-service.md) | Admin-page backing services — health check of PSAES DB and VIPP, field-count-by-content report, and the project-cost report CSV upload into rpt_proj_cost. | 8 | 8 | print-vipp, admin |
| [psaes-gridfe](nodes/psaes-gridfe.md) | React 18 + Vite SPA ("PSAES Command Center") that signs users in with Azure AD (MSAL), sends the token as a Bearer header on every /api call, and gates screens client-side by Azure group names. | 7 | 16 | ui, auth |
| [wfm-service](nodes/wfm-service.md) | Workflow-manager (WFM) message intake that stores a {uuid, action, payload} message in the wfm table and fires an @Async handler that does nothing yet. | 3 | 4 | print-vipp, wfm |

## interface (28)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [scan-test-ui](nodes/scan-test-ui.md) | /scanTest hub - pick account and scan program, manage test administrations and image app, then drive each scan-program document through the SPS (PDF, PETE, SRL, VIPP, TUES, VERI) or PV (VIPP, TUES, VERI) task stages, including SRL lock/unlock and Owatonna print. | 55 | 24 | ui, scan-test |
| [scan-test-api](nodes/scan-test-api.md) | Legacy verb-style Scan Test routes under /api (ScanTestController) - accounts, scan programs, task groups/tasks, stage moves (complete/remove/stage PDF/Tuesday Print), program documents, test admins and eligibility, SRL lock/anchors/documents/generation, VIPP PDF request and unformatted-SRL zip. | 49 | 17 | api, scan-program, workflow, legacy |
| [document-design-ui](nodes/document-design-ui.md) | Document design screens - PSAES Document Manager (/psaesmain, documents x program-session grid, uploads, copy page, test-case workflow), document field list (/psaesdoc, fields + barcode/check-digit settings) and content/OMR definitions (/psaescontent). | 23 | 17 | ui, documents |
| [pete-ui](nodes/pete-ui.md) | PETE (/pete) - the visual field placement editor; overlays an 83x47 timing-track grid on the document PDF page, places OMR bubble/barcode/litho/clip fields by clicking cells, edits field clips, and auto-generates litho fields. | 20 | 9 | ui, documents, litho, clip |
| [scan-programs-api](nodes/scan-programs-api.md) | Resource-style REST API under /api/scan-programs - scan program CRUD and image-app link, plus nested test administrations and their doc-code eligibility; the surface the Scan Test UI uses for test admins. | 18 | 8 | api, scan-program |
| [app-shell-ui](nodes/app-shell-ui.md) | Grid frontend shell - SSO login page, auth gate, header (logout, 30s user-alert poll), nav drawer, home/health/not-found pages. | 17 | 6 | ui, auth |
| [test-cases-api](nodes/test-cases-api.md) | REST routes of TestCaseController, TestCaseListFieldController and CsvTestDataController — generate test cases, upload/import test-data files (flat or CSV) and download test data. | 17 | 4 | interface, api, test-cases |
| [vipp-print-ui](nodes/vipp-print-ui.md) | VIPP and print screens - /vippPdfView to pick a VIPP request, view its generated PDF with test-case names, add it to print or stage it for Owatonna; /gridprint to list print requests and start a print run. | 17 | 8 | ui, vipp, print |
| [srl-ui](nodes/srl-ui.md) | SRL screens - /srlAnchors drag-and-drop board (plus JSON editor) for assigning fields to SRL record-type anchors per scan program, and /reviewSRL read view of the sorted SRL layout for one scan-program document. | 13 | 6 | ui, srl |
| [user-api](nodes/user-api.md) | User and alert REST routes under /api - list/look up/add/update/deactivate users, record a login, list and acknowledge a user's alerts; unauthenticated. | 13 | 4 | api, users |
| [vipp-api](nodes/vipp-api.md) | REST routes to request a VIPP PDF for a document, list/poll/download a user's VIPP PDFs, and the inbound VIPP-return callback (POST /api/postVippPdfLogs). | 12 | 3 | print-vipp, vipp, api |
| [documents-api](nodes/documents-api.md) | REST routes of DocumentController — document CRUD, page-PDF upload/download, document program/session settings, demo-page copy and the legacy litho generator. | 10 | 4 | interface, api, forms |
| [admin-ui](nodes/admin-ui.md) | /admin "Admin page" - PSAES health-check grid, a fields-by-content-type line chart, and a CSV upload whose endpoint does not exist; hidden from OWA Ops. | 8 | 2 | ui, admin |
| [fields-api](nodes/fields-api.md) | REST routes of FieldController — list a document's fields, add/update/delete a field (including clip-only edits), and list SRL labels for a scan-program document. | 8 | 2 | interface, api, forms |
| [litho-api](nodes/litho-api.md) | REST routes of LithoController — read litho settings/eligibility for a document, preview a litho plan, and generate (persist) litho fields. | 8 | 2 | interface, api, litho |
| [user-management-ui](nodes/user-management-ui.md) | /users User Management grid - list PSAES users; Admin can add, edit and activate/deactivate (inactive flag); view limited to Admin and Manager. | 8 | 3 | ui, auth, users |
| [admin-api](nodes/admin-api.md) | Admin/ops routes — GET /api/healthCheck, GET /api/getCntFieldsByContentType, GET /api/home echo, POST /api/uploadRptProjCost. | 7 | 2 | print-vipp, admin, api |
| [arl-api](nodes/arl-api.md) | POST /api/uploadUnformattedArl — multipart upload of a document's ARL file, imported into arl rows. | 7 | 1 | print-vipp, arl, api |
| [content-api](nodes/content-api.md) | REST routes of ContentController — list, add, update and delete OMR contents (character sets). | 7 | 2 | interface, api, forms |
| [extract-api](nodes/extract-api.md) | PASS-facing extract endpoints — POST /api/passSrlExtract (one document's SRL item layout) and POST /api/passDocCodesExtract (doc codes and SRL status for an account/admin). | 7 | 1 | print-vipp, extract, api, srl |
| [image-app-api](nodes/image-app-api.md) | REST API under /api/image-apps - list (optionally by account, active only by default), look up by name with the programs using it, get, create, update and soft-delete image apps. | 7 | 2 | api, scan-program |
| [print-api](nodes/print-api.md) | REST routes to list active print requests, queue a VIPP PDF for printing, and start a print run (POST /api/startPrintRun). | 7 | 3 | print-vipp, print, api |
| [prototype-pages-ui](nodes/prototype-pages-ui.md) | Routed but un-navigated prototypes - /adminMK2 (nested drag-and-drop SRL tree mock with hard-coded data) and /texteditor (flat-record viewer whose save/load are stubs); no API calls. | 5 | 0 | ui, legacy |
| [lakeside-ui](nodes/lakeside-ui.md) | /lakeside "Lakeside" clinical file-load status dashboard (interval tabs, records loaded/sent bar chart); its /api/clinicalIntervalList and /api/clinicalRequestSummary endpoints do not exist in the PSAES backend, so it only shows errors. | 3 | 0 | ui, legacy |
| [preview-ui](nodes/preview-ui.md) | /preview "Preview Scan" - a gallery of sample recharts chart types; also carries an unwired ad-hoc SQL runner (runQuery -> POST /api/query) whose endpoint does not exist. | 3 | 0 | ui, legacy |
| [unrouted-pages-ui](nodes/unrouted-pages-ui.md) | Grid-frontend files nothing imports - origDash (MUI template dashboard), calendar, wfm, unauthorized page, SignIn (old username login), and stray components/config (AddPsesField, IncrDecrButtons, DownloadButtonWithProgressBar, database.xjs, axios-configure.xjs.js, webpack.config.js). | 3 | 0 | ui, dead |
| [wfm-api](nodes/wfm-api.md) | /api/wfm/* — start, restart and poll a workflow-manager message; stored but never processed. | 2 | 1 | print-vipp, wfm, api, dead |
| [status-api](nodes/status-api.md) | POST /api/setCompleteStatus — stub that returns an empty StatusResponse; the /addStatusGroup builder is commented out. | 1 | 0 | print-vipp, status, api, dead |

## integration (4)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [vipp-server](nodes/vipp-server.md) | Xerox VIPP print-rendering server; PSAES hands it CSV data files through S3 drop folders (toVipp/documents, toVipp/labels, toVipp/printlist) and gets PDFs back via S3 plus the /api/postVippPdfLogs callback. | 12 | 1 | print-vipp, vipp, external |
| [azure-ad](nodes/azure-ad.md) | Microsoft Entra ID (Azure AD) tenant the grid frontend signs into with MSAL redirect; its ID token (groups claim) carries the PSAES role designations and is sent as the Bearer token to the API. | 11 | 0 | auth |
| [rms-pdf-repo](nodes/rms-pdf-repo.md) | Response Management (ICE) S3 pdfrepo bucket — every uploaded document PDF is also copied there, with bucket-owner-full-control, while document definition work still happens in ICE. | 6 | 0 | integration, s3 |
| [pass](nodes/pass.md) | PASS — external system that pulls SRL layouts and doc-code lists from PSAES through the /api/passSrlExtract and /api/passDocCodesExtract endpoints. | 5 | 1 | print-vipp, external, srl |

## datastore (2)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [psaes-postgres](nodes/psaes-postgres.md) | PSAES PostgreSQL database (schema psaes) - all application tables plus the scan_pgm_task view; schema owned by Flyway V1..V35 run from the psaes-flyway image; app connects through a Hikari pool built in CloudConfig. | 48 | 0 | datastore |
| [psaes-s3](nodes/psaes-s3.md) | PSAES S3 bucket (psaesBucket.path, us-east-1) holding uploaded documents, test-case files, ARL files, VIPP drop folders and returned PDFs, and print-run zips; accessed through the non-bean S3StorageManager. | 28 | 1 | datastore, print-vipp, s3 |

## event (4)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [vipp-pdf-returned](nodes/vipp-pdf-returned.md) | Inbound callback POST /api/postVippPdfLogs {key} telling PSAES that VIPP wrote a PDF to S3; completes the vipp_request and may trigger the print-run zip. | 11 | 1 | print-vipp, vipp, event, callback |
| [exception-log-purge](nodes/exception-log-purge.md) | Scheduled job (Spring @Scheduled, default daily 02:00) that deletes exception_log rows older than psaes.exception-log.retention-days (default 90). | 9 | 1 | job, scheduled, observability |
| [vipp-csv-submitted](nodes/vipp-csv-submitted.md) | A VIPP CSV data file is written to an S3 toVipp/ drop folder for the VIPP server to render (test deck, label sheet, print list or health check). | 8 | 1 | print-vipp, vipp, event |
| [vipp-health-check](nodes/vipp-health-check.md) | Scheduled job (@Scheduled fixedRate 60 min) that sends a one-line HealthChck CSV to VIPP and stamps health_check VIPP.last_request_date; the returned PDF stamps last_success_date. | 8 | 1 | print-vipp, vipp, job, scheduled |

## config (5)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [gridfe-route-access](nodes/gridfe-route-access.md) | Client-side role model of the grid frontend - role groups (admin, internal, manager, owaops, sps, tester) matched against Azure AD group names, plus per-route edit/view allow lists and a view deny list. | 65 | 2 | auth, ui |
| [psaes-app-config](nodes/psaes-app-config.md) | Spring configuration of the backend - application.properties defaults, the confd-rendered production properties (DB, S3 buckets, API URL, CORS origins), the hand-built Hikari datasource/JPA setup in CloudConfig, CORS for /api/**, logging with trace id, exception-log retention and SRL-lock settings. | 16 | 0 | config |
| [gridfe-env](nodes/gridfe-env.md) | Build/runtime settings of the grid frontend - VITE_* env vars (API base URL, Azure client/tenant/redirects, optional API scope, auth-header kill switch) rendered into /app/.env by confd from DynamoDB at container start. | 7 | 0 | config, ui |
| [flyway-migrations](nodes/flyway-migrations.md) | Schema ownership and conventions - Flyway V1..V35 SQL files in flyway/db run by a separate psaes-flyway container (not the app); entity @Column must match the DDL exactly, same PR for both halves, ddl-auto never mutating outside local dev. | 5 | 0 | config, schema, conventions |
| [psaes-deploy](nodes/psaes-deploy.md) | Build and deploy - Jenkins multibranch pipeline builds the jar (Maven, Corretto 17), builds the psaes-app and psaes-flyway images, pushes to the non-prod ECR and triggers the feature (PSAES-* branches) or release (master) manifest job; the app container renders application.properties with confd from DynamoDB and runs java -jar. | 1 | 0 | config, ops, deploy |

## flow (18)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [define-and-lock-srl](nodes/define-and-lock-srl.md) | Build a scan program SRL - edit anchor layouts per record type on /srlAnchors, generate and review each document SRL on /reviewSRL (which advances SPS and PV to VIPP), then Lock SRL after core-field validation. | 9 | 9 | flow, srl |
| [tuesday-print-run](nodes/tuesday-print-run.md) | Tuesday Print - Print Owatonna turns staged VIPP requests into print requests and advances the document; OWA Ops starts a print run, VIPP renders label and print-list sheets, and the returned sheets trigger the print-run zip with a billing list. | 7 | 10 | flow, print |
| [pass-srl-extract](nodes/pass-srl-extract.md) | PASS pulls a document SRL layout (units, items, scan field and intensity positions) by account code, admin code and doc code - gated on the document having reached SPS-VIPP - and lists doc codes with SRL status per administration. | 6 | 4 | flow, pass, srl |
| [add-document-to-scan-program](nodes/add-document-to-scan-program.md) | Add a doc code to a scan program from ScanTest - find-or-create the document and its program/session row, attach it, seed default-admin eligibility and start the SPS and PV task stages. | 5 | 6 | flow, scan-program |
| [advance-scan-test-stage](nodes/advance-scan-test-stage.md) | Move a scan-program document forward or back one task stage (SPS or PV) - completeStatus inserts a task approval for the next task by sequence, removeStatus deletes the top one; both serialize on the scan program row lock. | 5 | 4 | flow, workflow |
| [design-fields](nodes/design-fields.md) | Place and edit OMR fields on a document page in PETE (or the /psaesdoc list) - every field save validates the skip pattern and recomputes the field clip box; manual clip edits are clamped against neighbours. | 5 | 6 | flow, forms, clip |
| [create-scan-program](nodes/create-scan-program.md) | Create an account and a scan program from the ScanTest "Add Account / Program" dialog; the backend adds a default test administration seeded with all documents, then the UI adds each staged administration row. | 4 | 7 | flow, scan-program |
| [generate-litho](nodes/generate-litho.md) | Generate the litho fields of a document from PETE - read settings and eligibility, preview the plan, then delete generated litho fields and save one per planned page with ARL from the SRL anchor or the user start position. | 4 | 4 | flow, forms, litho |
| [request-vipp-test-deck](nodes/request-vipp-test-deck.md) | Request a VIPP test deck for a document - snapshot the user test cases into a VIPP CSV on S3, wait for the VIPP server PDF callback, review the PDF, then stage it for Tuesday Print (or add it to print directly). | 4 | 8 | flow, vipp |
| [generate-test-cases](nodes/generate-test-cases.md) | System-generate test data for a document - one QA list plus one list per content test case of the richest content, with litho, barcode and force-in-scan values, using SRL anchor positions when the document is in a scan program. | 3 | 5 | flow, test-cases |
| [import-arl](nodes/import-arl.md) | Upload the unformatted ARL file of a document from /psaesmain - store it in S3 under archive/arl/, re-parse it into arl rows (positions, lengths, valid values, force-in-scan) and mark the document arl_loaded. | 3 | 4 | flow, arl |
| [import-test-case-file](nodes/import-test-case-file.md) | Upload a pipe-delimited (flat) test-data file, validate it (errors block, warnings return in the body), store it in S3, then in a second call slice each record by ARL into test case lists. | 3 | 6 | flow, test-cases |
| [unlock-srl](nodes/unlock-srl.md) | Unlock a scan program SRL - clear the lock flags and move every document past SRL Process back to it, archiving the removed task approvals (and their VIPP notes) under one archive event for later restore. | 3 | 5 | flow, srl, workflow |
| [csv-test-data-round-trip](nodes/csv-test-data-round-trip.md) | Download the test data of a scan-program document as an editable CSV (columns from SRL-assigned fields), edit it in a spreadsheet, and upload it back into test case lists with EA rows and clip text. | 2 | 6 | flow, test-cases |
| [run-vipp-health-check](nodes/run-vipp-health-check.md) | Hourly VIPP round-trip check - send a one-line HealthChck CSV to the VIPP drop folder and stamp health_check VIPP last_request_date; the returned PDF stamps last_success_date; the admin page shows both. | 2 | 5 | flow, vipp, ops |
| [sign-in](nodes/sign-in.md) | Azure AD (MSAL) redirect sign-in to the grid frontend, then a PSAES user lookup by email that blocks unprovisioned or inactive users and stamps the last login; roles come from the token groups claim. | 2 | 8 | flow, auth |
| [upload-document-pdf](nodes/upload-document-pdf.md) | Upload a document page PDF - count pages, replace the S3 object under archive/docs/, copy it to the Response Management bucket, and (from ScanTest) move the document to the PETE stage. | 2 | 5 | flow, forms |
| [delete-program-document](nodes/delete-program-document.md) | Remove a document from a scan program (API only, no frontend caller) - delete its task approvals, approval history and eligibility rows, then the scan-program document; fails on FK once an SRL or a linked test case exists. | 0 | 4 | flow, scan-program |

## concept (26)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [arl-term](nodes/arl-term.md) | ARL = the layout file of a form’s scanned output record (field names, byte positions, lengths and valid values), uploaded per document and parsed into the arl tree. | 1 | 3 | glossary |
| [eligibility](nodes/eligibility.md) | Eligibility = which forms of a scan program a test administration covers - one test_admin_document row per covered form, no row means not covered. | 1 | 2 | glossary |
| [fallback-program](nodes/fallback-program.md) | Scan program id 999999 (and 9999999) = a catch-all program that bare documents are attached to when test data is handled outside a real scan program. | 1 | 3 | glossary |
| [force-in-scan](nodes/force-in-scan.md) | Force in scan = record positions whose value the scanner writes itself (not read from bubbles); test data must carry those fixed values. | 1 | 2 | glossary |
| [pgm-ssn](nodes/pgm-ssn.md) | pgm_ssn = program-session code <programNbr>-<ssn> of a document (document_pgm_ssn.pgm_ssn), used as the project on print requests and billing. | 1 | 2 | glossary |
| [processing-ssn](nodes/processing-ssn.md) | Processing SSN = the 3-digit processing session number of a test administration (test_admin.processing_ssn); unrelated to social security numbers. | 1 | 2 | glossary |
| [system-code](nodes/system-code.md) | System code = a test administration’s code in another system, one row per system in test_admin_system_code; today PASS and ADAM. | 1 | 1 | glossary |
| [account-code](nodes/account-code.md) | Account code = the 2-5 character customer code of an account (account.account_code), the same code ADAM stores as the client customer code. | 0 | 1 | glossary |
| [clip](nodes/clip.md) | Clip = the rectangle of the scanned page image cut out for a field, stored on field.clip as an automatic box plus an optional manual override. | 0 | 3 | glossary |
| [content-term](nodes/content-term.md) | Content = an OMR character set (0-9, A-Z, 01-12, litho, ...) that says which character each bubble of a field encodes. | 0 | 2 | glossary |
| [doc-code](nodes/doc-code.md) | Doc code = the identifier of a form (document.doc_code), 9 digits (sometimes written NNNNNN-NNN), used by scan programs, file names and PASS. | 0 | 1 | glossary |
| [ea-marks](nodes/ea-marks.md) | EA marks = erasure-analysis light marks - test values printed at 12%, 28% or 44% darkness (EA12/EA28/EA44) or EA99, to test how the scanner reads faint or erased marks. | 0 | 2 | glossary |
| [litho](nodes/litho.md) | Litho code = the serial number printed and bubbled (in binary) on each sheet of a booklet so scanned pages can be tied back together. | 0 | 2 | glossary |
| [owatonna](nodes/owatonna.md) | Owatonna (OWA) = the operations site whose team prints test decks; "Print Owatonna" releases staged decks to print, and the owaops role runs print runs. | 0 | 2 | glossary |
| [pete](nodes/pete.md) | PETE = the visual field placement editor (/pete) that overlays the 83 x 47 timing-track grid on a page PDF; also the SPS-PETE stage of the scan test. | 0 | 2 | glossary |
| [record-type](nodes/record-type.md) | Record type = the scanner record type of a form (e.g. 01, 17, 99), document.record_type; it selects the SRL baseline and anchor layout used for the form. | 0 | 2 | glossary |
| [row-density](nodes/row-density.md) | Row density = the bubble grid density of a form: "8" means the 6x8 high-density grid, anything else 6x6; it changes litho positions and VIPP rows. | 0 | 2 | glossary |
| [scan-program](nodes/scan-program.md) | Scan program = one customer program’s scanning configuration under an account (program name, legacy SSN, cost centre, row density, SRL lock, image app) and the forms it scans. | 0 | 2 | glossary |
| [skip-pattern](nodes/skip-pattern.md) | Skip pattern = how a field’s characters are spaced on the grid - blank or 0 contiguous, one number for a uniform gap, or a comma list of per-gap counts. | 0 | 2 | glossary |
| [sps-pv](nodes/sps-pv.md) | SPS and PV = the two scan-test task groups, "SPS Scan Program Testing" (task group 1) and "PV Testing" (task group 2); each is a queue of stages a scan-program document passes. | 0 | 2 | glossary |
| [srl-term](nodes/srl-term.md) | SRL = scan record layout - which label (record type, doc code, item responses, intensities, litho, batch pass) sits at which byte position of the record the scanner writes for a sheet. | 0 | 4 | glossary |
| [task-stage](nodes/task-stage.md) | Task = one workflow stage (SPS-PDF, SPS-PETE, SPS-SRL, SPS-VIPP, SPS-TUES, SPS-VERI, SPS-APRV, PV-...); a document’s stage is its highest task approval in the group. | 0 | 3 | glossary |
| [test-admin-term](nodes/test-admin-term.md) | Test admin = a test administration (a customer testing window, e.g. spring 2026) that a scan program scans for - not a person. | 0 | 2 | glossary |
| [tuesday-print](nodes/tuesday-print.md) | Tuesday Print = the weekly print batch of test decks, and the SPS-TUES / PV-TUES stage where documents wait for it. | 0 | 3 | glossary |
| [vipp-slug](nodes/vipp-slug.md) | Slug = one mark VIPP prints on a test sheet (a filled bubble, a text character, a barcode or a litho bit), written as page / value / xy / grid-type in the VIPP CSV. | 0 | 2 | glossary |
| [vipp](nodes/vipp.md) | VIPP = Xerox Variable-data Intelligent PostScript Printware; here the print-rendering server that turns PSAES CSV data files into filled-in test-deck PDFs, label sheets and print lists. | 0 | 3 | glossary |

## capability (23)

| node | summary | in | out | tags |
|---|---|---|---|---|
| [scan-program-setup](nodes/scan-program-setup.md) | Scan program setup - create customer accounts and scan programs and add the forms each program will scan. | 1 | 4 | capability |
| [arl-loading](nodes/arl-loading.md) | ARL loading - upload a form’s scanner record layout so PSAES knows every output position, its length and its allowed values. | 0 | 3 | capability |
| [document-management](nodes/document-management.md) | Document manager - create scannable forms (doc codes), upload their page PDFs, edit program/session and barcode settings, and copy fields between pages. | 0 | 4 | capability |
| [error-trace-log](nodes/error-trace-log.md) | Error trace log - every API error returns a trace id and is stored, so support can look up what failed and for whom. | 0 | 3 | capability |
| [field-clip-boxes](nodes/field-clip-boxes.md) | Field clip boxes - every field gets an automatic image-clip rectangle that designers can adjust, used to cut answer images for hand scoring and image apps. | 0 | 4 | capability |
| [image-app-assignment](nodes/image-app-assignment.md) | Image app assignment - link each scan program to the imaging application its scans are processed in. | 0 | 3 | capability |
| [in-app-alerts](nodes/in-app-alerts.md) | In-app alerts - the header bell tells users when long jobs finish (test data built, CSV processed, VIPP PDF returned). | 0 | 2 | capability |
| [litho-generation](nodes/litho-generation.md) | Litho code generation - automatically add the sheet serial-number (litho) fields to every folded sheet of a booklet, positioned from the SRL. | 0 | 3 | capability |
| [omr-content-library](nodes/omr-content-library.md) | OMR content library - maintain the character sets (0-9, A-Z, months, litho, ...) that answer fields can use. | 0 | 4 | capability |
| [ops-admin-page](nodes/ops-admin-page.md) | Operations admin page - see whether the PSAES database and the VIPP server are healthy and how many fields use each content type. | 0 | 4 | capability |
| [pass-srl-feed](nodes/pass-srl-feed.md) | PASS layout feed - PASS reads each form’s scanner layout and the list of forms per administration from PSAES. | 0 | 2 | capability |
| [scan-test-workflow](nodes/scan-test-workflow.md) | Scan test workflow - track every form of a scan program through the SPS and PV test stages, from PDF to approval. | 0 | 5 | capability |
| [srl-layout-builder](nodes/srl-layout-builder.md) | SRL layout builder - lay out, per record type, which answer lands at which position of the scanner output record, then generate each form’s layout. | 0 | 4 | capability |
| [srl-lock](nodes/srl-lock.md) | SRL lock - freeze a scan program’s record layout once its core fields line up across record types; unlocking sends forms back to the SRL stage. | 0 | 5 | capability |
| [sso-sign-in](nodes/sso-sign-in.md) | Pearson SSO sign-in - staff sign in with their Pearson Azure AD account; PSAES lets them in only if a PSAES user record exists for their email and is active. | 0 | 4 | capability |
| [system-generated-test-data](nodes/system-generated-test-data.md) | System-generated test data - one click builds a full set of test answer sheets that exercise every bubble pattern of a form. | 0 | 3 | capability |
| [test-administrations](nodes/test-administrations.md) | Test administrations and document eligibility - record each customer administration a program scans for, its processing SSN and its codes in PASS and ADAM, and which forms it uses. | 0 | 4 | capability |
| [test-data-file-import](nodes/test-data-file-import.md) | Test data file import - upload a prepared flat file of test records, get row-level errors and warnings, then turn it into test sheets. | 0 | 4 | capability |
| [test-data-spreadsheet](nodes/test-data-spreadsheet.md) | Test data in a spreadsheet - download test data as a CSV laid out by the SRL, edit it in Excel, and upload it back. | 0 | 3 | capability |
| [tuesday-print-batching](nodes/tuesday-print-batching.md) | Tuesday Print batching - collect approved test decks into a weekly print run with shipping labels, a print list and a billing list for the print shop. | 0 | 4 | capability |
| [user-management](nodes/user-management.md) | User management - administrators add PSAES users, edit their details and deactivate them. | 0 | 3 | capability |
| [vipp-test-decks](nodes/vipp-test-decks.md) | VIPP test decks - turn a form’s test data into a print-ready PDF of filled-in answer sheets, rendered by the VIPP print server. | 0 | 4 | capability |
| [visual-field-design](nodes/visual-field-design.md) | Visual field design (PETE) - place a form’s answer bubbles, barcodes and write-in grids by clicking on the page image over the scanner timing-track grid. | 0 | 4 | capability |