Packet Station
Digital job packets for the PESCO shop floor. A packet moves through each department on screen instead of on paper. VISUAL releases the work and Packet Station builds the packet with the drawing from M-Files at the rev the job pull calls. Clerical checks anything flagged. Warehouse pulls parts and records heat numbers, MTRs and shorts. A supervisor assigns a station and welder. The station logs welds on the weld map, works the checklist and runs the timer. The supervisor sends it to Q.C. Q.C. inspects, accepts or rejects, and adds reports. Clerical closes the job in VISUAL, exports the manufacturing data book PDF and files it. A change in VISUAL to a packet already in the shop goes to Clerical as a change order before it reaches the shop.
This repo is the rebuild of Packet Station as a server application: Docker Compose on docker-1, PostgreSQL 16, a Python server that enforces every rule, a worker for the VISUAL feed and M-Files drawing lookups, and a React frontend as a pure client. Sign-in is PESCO's Active Directory. VISUAL is read through VisualKit and M-Files through MFilesKit, read-only.
Status
Rebuild in progress. Phase 9 done: the Admin page completed (departments, profiles with the CSV import, checklists, security settings and alerts, the access log, who is in, the stamp check), the nightly AD reconcile and the 15-minute role refresh, the integrity job, notifications by email with rules per event, nightly database backups with a rehearsed restore, and dependency scanning in CI. SethD's changes C1 to C11 (Gitea, 2026-10-26 and 2026-10-28) were built on 2026-10-30.
People can sign in, set up projects and units, make hand drafts, attach a drawing, and send a packet to the warehouse, a department or Q.C. The worker reads released work orders from VISUAL on a schedule, makes and updates drafts, opens change orders on packets already in the shop, looks drawings up in M-Files and attaches them at the rev VISUAL calls. Clerical sees it all on the From VISUAL panel and in the Flagged and Changes to approve columns; Admin sets the feed up on the Feed tab. Warehouse works its task board (waiting, being pulled, on hold, pulled, released), pulls parts line by line with heat numbers, shorts, receipts and MTRs (the department supervisor then approves each received short with a signature), and releases to the supervisor once every line is pulled or short and every pulled line has a heat. A supervisor assigns the packet to a station and a welder. The welder's Stall screen lists the packets assigned to them, each at the station the supervisor picked. The welder starts the clock, marks welds on the drawing, places the heat table, finishes the checklist and submits with a PIN signature, and the supervisor sends it to Q.C. or routes it to another department with the marks carried. Department supervisors verify change orders with a signature. Q.C. inspects the packet on its own tab (the check items, a visual result per weld, NDE, hardness, notes), accepts it to the data book, to Shipping or on to another department with a PIN signature, or rejects it back to the supervisor with a reason and, when there is one, an NCR number. A packet rejected without an NCR number needs one at the accept, and a packet with a short not yet approved cannot be accepted as complete. Q.C. keeps project folders of documents per project and unit (ITP, WPS / PQR, procedures, certificates) where a new revision supersedes the old one and nothing is deleted, adds reports to a packet for the data book and takes them out with a reason, and works each unit's digital ITP from the Q.C. template through line initials, N/A, rejects with NCR numbers, section block signatures and a sign-off. Open hold and witness points show as a warning on the unit's packets. The feed marks a VISUAL packet closed in VISUAL when it sees every work order closed, and the packet moves to Clerical's "Ready for data book" column by itself; Clerical confirms a hand packet by hand. Clerical files the packet with a signature once VISUAL is closed, the unit's ITP is complete and every short is approved. Filing seals the packet with an HMAC and builds the manufacturing data book on the server, stored on the seal. The data book goes to the customer and has no history pages; the history stays in Packet Station. IT can reopen a filed packet with a reason and a signature, which keeps the broken seal and its data book. Anyone who can open a packet can view or download the data book, the job traveler with the work order QR codes, the ITP PDF and the traceability CSV, and print a stamped copy of the traveler, the drawings with the heat or weld map, the drawings without markup, the VOID sheets, the data book or any document. A print goes straight to the browser's print dialog. Every copy carries a stamp signed with the seal key, and every print and export is logged. Admin, Q.C. and Clerical check a copy's stamp on the Stamp check screen. Project Management and Admin read the PM reports. The ITP sign-off files the signed ITP PDF. Each department supervisor edits their department's checklist on the Checklists screen; a stage keeps the list it started with. An Admin manages departments and stations, welder stamps and station limits (one at a time or from a CSV), any department's checklist, the session and lockout settings, and who gets which email. The worker reconciles users with AD every night, re-reads each signed-in person's groups every 15 minutes, checks seals, files and the audit chain every night, and checks that the nightly backup ran. Problems and events reach people by email through app-03. Every packet write goes through the server policy. The old build on M:\Production\Packet Station stays the live system until go-live. The new system starts empty; nothing is migrated from M:.
| Area | Exists yet? |
|---|---|
| Repo, docs, CLAUDE.md | Yes (phase 0) |
Image, compose, CI, doctor, migration runner, security headers, build version endpoint |
Yes (phase 0, image and stack verified on docker-1) |
| Sign-in (AD password, PIN on registered devices), sessions, lock screen, Account settings, Admin shell, audit, SSE | Yes (phase 1, verified against the Samba DC in the CI stack on docker-1) |
| Schema, policy engine, packet API, projects and units, assets, Clerical screen, packet page | Yes (phase 2, verified against PostgreSQL and the Samba DC in the CI stack on docker-1) |
| VISUAL feed, M-Files drawings, change orders from the feed, From VISUAL panel, Admin Feed tab and resource map | Yes (phase 3, run once against VISUAL DEV and the vault from a developer machine; fixture-driven in CI) |
| Warehouse screen, pull table, shorts and receipts, MTRs, release gate, upload kinds, optional ClamAV, storage alert | Yes (phase 4, verified in the CI stack on docker-1) |
| Supervisor and Stall screens, weld map, heat table, station clock, change-order verification | Yes (phase 5, verified in the CI stack on docker-1) |
| Q.C. screen, inspection, Q.C. folders, packet documents, digital ITP, hold-point warnings | Yes (phase 6, verified in the CI stack on docker-1) |
| Close and file, HMAC seal with the data book, reopen, data book, traveler and ITP PDFs, traceability CSV, prints and the print log | Yes (phase 7) |
| Project Management screen (six tabs, periods, health, CSV and PDF reports), the find bar completed (search, filters, quick flags, Mine, Board and List, saved per browser), presence, motion, iPad layout | Yes (phase 8, verified in the CI stack on docker-1) |
| Admin completion (departments, profiles, checklists, Security, access log, who is in, stamp check, Notifications), AD reconcile and role refresh, integrity job, email notifications, backups and restore, CI dependency scan | Yes (phase 9) |
SethD's changes C1 to C11: over target on VISUAL ticket hours, the Q.C. reject reason and the NCR on the accept, the ITP complete before filing, prints to the print dialog, filing blocked until VISUAL closes, no history pages in the data book, supervisor approval of received shorts, checklists per department (/checklists), the stamp check for Q.C. and Clerical (/stamp-check), PM reports for PM and Admin only, the Stall screen by assignment |
Yes (2026-10-30) |
| Regression bench and go-live | No (phase 10) |
Phases
The full plan is in docs/PLAN.md.
| Phase | What it delivers |
|---|---|
| 0 | Skeleton: repo, docs, Dockerfile, compose, CI, packetstation doctor, migration runner, headers and CSP. |
| 1 | Identity: AD sign-in, sessions, optional PIN, devices, signatures, audit, SSE, frontend shell and theme. |
| 2 | Core domain: schema, policy engine in Python, packet API, Clerical screen, packet page. |
| 3 | VISUAL feed and M-Files drawings in the worker, change orders, Clerical "From VISUAL" panel. |
| 4 | Warehouse: task board, pull table, heats, MTRs, shorts, upload pipeline. |
| 5 | Shop: supervisor and stall screens, weld map, heat table, timer, change-order verification. |
| 6 | Q.C.: inspection, accept and reject, Q.C. documents, digital ITP. |
| 7 | Close and file, HMAC seals, server-side PDFs (data book, traveler, ITP, prints, stamps). |
| 8 | Project Management screen, find bar, list view, presence. |
| 9 | Admin completion, AD reconcile, integrity job, notifications, backups and restore. |
| 10 | Regression bench, hardening, go-live and paper-fallback docs. |
Folder map
CLAUDE.md README.md CHANGELOG.md pyproject.toml Dockerfile .env.example
docs/ the brief, the plan, security, deploy, feed, policy, schema, go-live, paper fallback
server/packetstation/ the Python package: app, worker, CLI, migrations, policy, domain, feed, drawings, PDFs
frontend/ Vite + React + TypeScript client
tests/ server tests (pytest), e2e scenarios (Playwright), synthetic fixture generator
deploy/ compose files (base, NPM overlay, CI overlay), PostgreSQL init, Samba AD for CI
docker/ the image entrypoint
scripts/ host backup and restore scripts, systemd timer
.gitea/workflows/ CI
Not in git: .env, tests/fixtures/local/, reference/, recordings/. Real job data stays out of git and CI.
How to run
Developer machine:
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
.venv\Scripts\python -m pytest
cd frontend && npm ci && npm run build
packetstation doctor
visualkit and mfileskit install from PESCO's Gitea index with --index-url. Everything else installs from public PyPI in a separate step. See docs/DEPLOY.md.
Test stack on docker-1:
docker compose -p packetstation-test --env-file ~/packetstation/test/stack.env \
-f deploy/compose.yaml -f deploy/compose.proxy.yaml up -d
Phase 2 adds /api/projects, /api/units, /api/packets (header, transitions, work orders, pages, documents, BOM, shorts, welds, heat tags, heat table, stage, checklist, clock, warehouse stage, Q.C., change orders, log, seal), /api/assets and /_blob/{id}. Every packet read carries can, blocked and holder from the policy. See docs/POLICY.md and docs/SCHEMA.md.
The packetstation command has doctor, migrate, app, worker, job run <name> (one job in the foreground), fixtures use N (switch the fixture state, never on prod), ad-groups --list (the 50 AD group names the app expects) and ad-refresh (the AD reconcile once, in the foreground, with the same refusal guard as the nightly job).
Phase 3 adds the worker (packetstation worker: APScheduler, the visual-feed, drawing-lookup and housekeeping jobs, settings re-read on every fire, run now through job_requests), the VISUAL and drawing cache tables (migration 0004), /api/feed/*, /api/jobs/*, /api/admin/feed/*, rev approval and hand uploads under /api/packets/{id}, and the synthetic fixture generator (python -m tests.fixtures.generator --out DIR) that CI feeds the worker with. See docs/FEED.md.
Phase 6 adds the Q.C. screen (/qc: numbers, boards, project folders), GET /api/qc/home, GET /api/qc/folders with the project and unit folder reads, POST /api/qc/docs (a new revision supersedes the old row), the per-key Q.C. endpoints under /api/packets/{id}/qc, document kinds as a closed set with take-out reasons, and the digital ITP under /api/units/{id}/itp and /api/itps/{id} (start, line sign and unsign, N/A, reject with NCR, block sign, sign-off, reopen, log). The ITP PDF filed on sign-off is a hook for phase 7. See docs/POLICY.md "Q.C. (phase 6)".
Phase 7 adds the close and file panel, confirm_open_wos on the file transition (409 open_work_orders without it; removed on 2026-10-30 by change C5, since filing is now blocked while VISUAL shows a work order open), the data book built and stored on the seal at filing, GET /api/packets/{id}/pdf/databook, GET /api/packets/{id}/pdf/traveler, GET /api/packets/{id}/export/traceability.csv, GET /api/packets/{id}/print/{kind} (traveler, map-h, map-w, clean, void, databook, doc), GET /api/packets/{id}/prints, GET /api/itps/{id}/pdf and GET /api/itps/{id}/print, and the print_log table (migration 0008). The PDFs are built on the server with reportlab 5.0.1, pypdf and pypdfium2; the heat and weld map rasters use Pillow 13.0.0. Both are pinned in pyproject.toml and server/requirements.txt, and need no system package or font in the image. See docs/POLICY.md "Phase 7: close, file, PDFs and prints".
Phase 8 adds the Project Management screen (/pm) and its API under /api/pm (overview, projects with expand=, aging, hours, quality, find, export.csv?table=<key>|jobs|all, report.pdf), read by PS-ProjectMgmt and Admin only since change C10 (any signed-in role in phase 8) and writing nothing; every export is logged as report exported in the audit and the print log. The find bar params (q, status, dept, station_id, welder_id, flags, flag, sort, mine_screen, mine_station_id (ignored since change C11), facets) are read by GET /api/packets and by the shop, stall, warehouse and Q.C. boards, so the server applies every filter; the KPI numbers follow the project pick only. Presence over /api/events now carries the role and drops locked sessions (session events locked and unlocked). No new table or migration. See docs/POLICY.md "Phase 8: Project Management, find bar, presence".
Phase 9 adds, under /api/admin: departments (list, PATCH /departments/{code}, POST /departments), PATCH /users/{id}/profile, POST /users/import (CSV preview and apply), checklists, security/settings, security/alerts, security/integrity, access-log and access-log.csv, presence, stamp-verify and stamp-verify/pdf, directory-flags, ad/reconcile, and notifications (rules, group search, test send, sent log). POST /api/admin/ad/refresh now asks the worker for an ad-reconcile run and answers 202. Any signed-in person reads GET /api/account/notifications, and opts out of an event type with PUT /api/account/notifications/{event_type} (password session; security events cannot be turned off). The Admin page gains the tabs Departments, Profiles, Checklists, Security, Access log, Who is in, Stamp check and Notifications, and Account settings gains a Notifications section. The worker gains six jobs: ad-reconcile (01:30), session-refresh (every 15 minutes), integrity (04:00), backup-check (07:15), notify-send (every minute) and notify-digest (every 5 minutes). Migration 0010 adds the notification tables, the integrity findings and the profile switch. See docs/POLICY.md "Phase 9: Admin, notifications, reconcile" and docs/FEED.md "Phase 9 jobs".
SethD's changes (built 2026-10-30, docs/PLAN.md changes C1 to C11) add two screens, /checklists (department supervisors and Admin) and /stamp-check (Admin, Q.C. and Clerical), both linked in the top bar. The API gains GET /api/checklists, GET and PUT /api/checklists/{dept}, POST /api/stamp-verify and POST /api/stamp-verify/pdf (the /api/admin paths stay as aliases), GET /api/stall/mine (the Stall screen; the station picker is gone) and POST /api/packets/{id}/shorts/receipts/{receipt_id}/approve. The Q.C. accepts take ncr, and the packet read gains ncr_required, shorts and shorts_unapproved. Every /api/pm/* endpoint is for PS-ProjectMgmt and Admin only. Every print goes through frontend/src/lib/printPdf.ts. The data book has six sections. Migration 0011 adds short_approvals and packet_stages.checklist_template. See docs/POLICY.md for the rules and docs/SCHEMA.md, "Seth's changes", for the schema.
Backups run on the host, outside the app: scripts/backup/ps-backup.sh (nightly pg_dump of each stack from a systemd timer at 02:00 Denver time, 7 kept, with markers the worker checks) and scripts/backup/ps-restore.sh (restore into a fresh database, copy assets back, check hashes, compare row counts). scripts/backup/README.md and docs/DEPLOY.md "Backup" have the install steps and the restore rehearsal of 2026-10-21.
CI stack with the Samba domain controller and the Playwright scenario, on a Docker host:
deploy/ci/make-secrets.sh
docker compose -p packetstation-ci --env-file deploy/ci/ci.env -f deploy/compose.yaml -f deploy/compose.ci.yaml up -d --build --wait
docker compose -p packetstation-ci --env-file deploy/ci/ci.env -f deploy/compose.yaml -f deploy/compose.ci.yaml --profile e2e run --rm playwright
docker compose -p packetstation-ci --env-file deploy/ci/ci.env -f deploy/compose.yaml -f deploy/compose.ci.yaml down -v
CI scans the dependencies on every run: pip-audit over server/requirements.txt fails on any known vulnerability, and npm audit --audit-level=high fails on a high or critical one.
Server tests that need PostgreSQL run when TEST_PG_SUPERUSER_URL is set; the ones that need the domain controller run when the TEST_LDAP_* variables and TEST_DC_USERS_FILE are set. See deploy/samba/README.md.
Docs
- docs/BRIEF.md: the brief this rebuild follows.
- docs/PLAN.md: the approved phased plan and open questions.
- docs/SECURITY.md: old layers and where they live now, the new controls, the requirement ID table.
- docs/DEPLOY.md: host, stacks, secrets, NPM proxy host, doctor, notifications, backups and the restore rehearsal.
- docs/FEED.md: the worker and its jobs, the VISUAL feed, the packet rules, the fingerprint, the drawing decision table, the flags and the feed settings.
- docs/POLICY.md: who may do what, the preconditions, the order of checks, concurrency, and the tightenings against the old build.
- docs/SCHEMA.md: the database schema (migrations 0001 to 0011).
- docs/GO-LIVE.md: go-live procedure (phase 10).
- docs/PAPER-FALLBACK.md: what the shop does when the server is down (phase 10).
- CHANGELOG.md: what changed.
- CLAUDE.md: rules for Claude Code sessions in this repo.