An electronic Quality Management System for regulated (GxP) manufacturing, built in the open. Deviations, investigations, actions, CAPAs, change controls and controlled documents run on one configurable engine. The rules that make a record trustworthy (who may act, who may sign, what must be complete, what gets logged) live inside the database, so no client, human or AI, can route around them.
Status (2026-10-06): development paused since 2026-09-21. Not validated. Six Record Types are built end to end: schema, server, web screens and tests. No claim of regulatory compliance is made or implied. Validation (IQ/OQ/PQ) was deliberately deferred until after development. Treat this as a worked example, not as a system you could qualify.
Three layers, from the outside in. The further in, the more rules.
flowchart LR
P["Person<br/>(QA, process owner)"] --> W["Web client<br/>Next.js<br/><i>renders screens</i>"]
W --> A["Server<br/>FastAPI<br/><i>verifies who you are</i>"]
AI["AI agent<br/>(separate platform)"] -. "published contract<br/>read and propose only" .-> A
A --> DB[("PostgreSQL<br/><b>the rules live here</b>")]
DB --> AT["Audit trail<br/>who, what, when, why"]
DB --> ES["Electronic signatures<br/>+ hash of the signed content"]
The web client and the server are thin. Every write to a GxP table goes through a
SECURITY DEFINER database function; the application role holds no direct INSERT, UPDATE or
DELETE at all, only an enumerated list of verbs that grows by an argued decision in docs/adr/.
sequenceDiagram
autonumber
actor U as Person
participant W as Web
participant A as Server
participant D as Database
U->>W: Presses "Approve" and enters their signing password
W->>A: Request with their session
A->>A: Is the session valid and the user still active?<br/>(asked of the auth server on every request)
A->>D: execute_transition(record, target state)
D->>D: Does their role allow this transition?
D->>D: Are they someone other than who did the previous step?<br/>(segregation of duties)
D->>D: Is the record complete?
alt Any check fails
D-->>A: Refusal with a coded reason
A-->>W: "You can't, because..."
else All checks pass
D->>D: Change the state
D->>D: Store the signature + hash of exactly what was signed
D->>D: Write the audit trail, column by column
D-->>W: Done
end
The server never trusts a client to say who it is: the acting user is derived from a session the
server verified itself (app/api/auth.py, docs/adr/0080). The state machine is
declaration-driven: states, transitions, permitted roles, signature meanings and segregation
rules are rows in tables, and the engine that executes a transition has no branch on Record Type.
There is no AI code in this repository, and that is deliberate. An assistant lives on a separate
platform and talks to this system through a versioned contract (contracts/). It may read and
propose. It may not decide.
flowchart LR
AI["AI agent"] -- "proposes a value<br/>+ where it came from" --> PR["Proposal<br/>(pending)"]
PR --> H{"Person reviews"}
H -- "accept / modify" --> R["Enters the record<br/>as that person's act"]
H -- "reject" --> X["Kept, with the reason"]
AI -. "approve, sign, close" .-x NO["Refused by the database"]
Every proposal carries an AI Provenance Record (which model, which inputs, when), and the audit trail tags every change with its source: UI, API, Agent or System. Approving, signing, closing and disposing are not agent operations, and that check lives in the domain, not in the menu.
| Record Type | What it is | Relationship |
|---|---|---|
| Deviation | Something went wrong | Root record |
| Investigation | Why it happened | Child of a Deviation |
| Action | A concrete task with an owner and a due date | Child of a Deviation, CAPA or Change Control |
| CAPA | Corrective and preventive action | Root record that remembers its origin |
| Change Control | A planned change | Root record |
| Controlled Document | An SOP; going effective assigns training | Root record |
Designed but not built: Quality Event, Audit Received, Audit Performed, Finding.
Measured on 2026-10-06: 262 migrations, 78 pgTAP suites planning 3,273 assertions,
114 pytest modules, 97 ADRs. Re-measure with
python supabase/apply_migrations.py --dry-run, ls supabase/tests/*.test.sql | wc -l,
pytest tests/ --collect-only -q and ls docs/adr/[0-9]*.md | wc -l.
| Path | Contents |
|---|---|
supabase/ |
The schema as ordered migrations, the pgTAP suites that hold it, and schema/current.sql, the generated snapshot of the live schema |
src/ · tests/ |
Python domain layer, one module per Record Type, and the pytest suite |
app/api/ · app/web/ |
FastAPI server and the Next.js client |
config/ |
One YAML per Record Type declaring what is built; a parity test compares it with the schema and the Python layer |
contracts/ |
The QMS Capability Contract: OpenAPI, MCP tool list, provenance schemas, generated client |
docs/ |
The governing design documents and docs/adr/, one file per architecture decision |
CONTEXT.md |
Domain glossary: terms fixed as they settle |
superseded/ |
The validation layer of the previous version, kept as historical record |
Python 3.12 (pinned in .python-version). uv sync, then uv run pytest -rs; every
database-touching module is collected and skipped unless AIQMS_DB_URL is set in a git-ignored
.env. Copy .env.example, which names every variable with an empty value and says
what each one is for.
Continuous integration (.github/workflows/aiqms-ci.yml) runs on every push and pull request:
- pytest without a database, proving the suite collects and skips cleanly;
- pytest against a disposable PostgreSQL built from zero (all migrations in order, the user cast seeded);
- the full pgTAP suite against a second disposable database;
- the web client:
npm ci,npm run typecheck,npm run build.
Locally, the pgTAP suites are python supabase/run_pgtap.py and need a PostgreSQL with pgtap,
pgcrypto and plpgsql_check. The demo starts with python app/run_demo.py (API and web client as
local processes); docs/demo-script.md is what to show and which control to break live. Public
hosting is out of scope.
GAMP category 5 (custom-built). Active references: 21 CFR Part 11, EU GMP Annex 11, GDPR. The AI-specific frame was verified against primary sources on 2026-08-10:
- EU GMP Annex 22 (AI in GMP) is not adopted. Its consultation closed on 7 October 2025 and there is no published adoption date. Its draft ban on generative AI and LLMs in critical GMP applications is being reconsidered by EMA after a workshop on 30 June – 1 July 2026.
- The EU AI Act does not classify AI in pharmaceutical manufacturing as high-risk. No pharmaceutical legislation appears in Annex I Section A, and Annex III has no pharmaceutical category. Regulation (EU) 2026/1744 deferred the high-risk obligations to 2 December 2027 (Annex III) and 2 August 2028 (Annex I).
Not high-risk is not unregulated: Annex 11, Part 11 and GMP apply regardless. The design targets the stricter standard, because reworking a signature flow in an already-validated system is the expensive kind of mistake.
This public repository starts from a single snapshot commit. The development history behind it
(commits, pull requests and issues) is kept in a private archive. References in the code and docs
of the form aristo-Cat/AIQMS#NN, commit hashes, and paths under work/ or evidence/ point into
that archive and are kept as written: an applied migration is never edited (docs/adr/0077).