Skip to content
aristo-CatPublic

About

An eQMS for GxP manufacturing where AI proposes and only a person decides. Controls enforced in PostgreSQL. Not validated; worked example.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

AI-QMS: an eQMS where AI proposes and only a person decides

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.

How it works

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"]
Loading

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/.

What happens when someone presses "Approve"

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
Loading

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.

Where AI fits

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"]
Loading

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.

What is built

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.

Where things are

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

Running it

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.

Regulatory frame

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.

About this repository's history

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).

License

Apache License 2.0. See LICENSE and NOTICE.

About

An eQMS for GxP manufacturing where AI proposes and only a person decides. Controls enforced in PostgreSQL. Not validated; worked example.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages