Four blog posts into the OKF-for-life-sciences debate, we’ve established three things: the underlying pattern is correct, the format is wrong for regulated storage, and the vendors are building the API layer. What we haven’t answered is the most practical question of all: if you’re building a QMS from scratch, what do you actually build?

Ten independent analyses were asked that exact question. All ten converged on the same architecture. Not approximately — the same architecture, down to the database choice.

The unanimous verdict

Every analysis landed here:

Layer Role OKF involvement
PostgreSQL database Source of truth, audit trail, signatures None — standard relational tables
Knowledge graph Relationship traversal SQL/PGQ property graph over existing tables
Agent API Structured context for AI agents OKF-shaped responses generated on demand
Human UI Forms, workflows, dashboards None — standard web frontend

The database holds the validated state. The knowledge graph captures relationships. The API serves OKF-shaped projections to agents. The human UI looks like a normal QMS. No markdown files on disk. No git repos. No parallel document format.

OKF becomes the language the QMS speaks to AI agents — not the storage engine, not the database, not the user interface.

Why PostgreSQL (and why it matters now)

Every analysis named PostgreSQL specifically. Two reasons:

First: JSONB columns for flexible metadata. Quality documents have rigid required fields (document ID, version, status, effective date) but also variable metadata depending on type. A deviation needs severity, root cause category, and impacted batches. A validation protocol needs acceptance criteria, statistical method, and sample size. PostgreSQL’s JSONB lets you enforce the required fields in relational columns while storing type-specific metadata in a validated JSONB field with JSON Schema constraints.

Second: PostgreSQL 19 ships native graph queries. This is the development that changes the architectural calculus. PostgreSQL 19, in beta since June 2026, implements SQL/PGQ — the ISO SQL:2023 Property Graph Queries standard. You define a property graph as a view over your existing relational tables, then query it with MATCH syntax:

SELECT * FROM GRAPH_TABLE (quality_graph
    MATCH (dev IS deviation WHERE dev.id = 'DEV-2026-102')
          -[IS involved_equipment]->(eq IS equipment)
          -[IS governed_by]->(sop IS sop)
          -[IS validated_by]->(vp IS validation_protocol)
    COLUMNS (eq.name, sop.doc_id, vp.doc_id, vp.status)
);

This traverses Deviation → Equipment → SOP → Validation Protocol in a single query. No separate graph database. No Neo4j. No Apache AGE extension. No data migration. The graph runs over the same tables that hold your validated data, using the same indexes.

For a QMS where the knowledge graph is a core feature — “show me everything connected to this deviation across three hops” — this eliminates the biggest architectural objection to building graph capabilities into a greenfield system.

The OKF-shaped API contract

Here’s what the agent-facing API looks like. Every quality object exposes an endpoint that returns an OKF-shaped response:

GET /api/v1/okf/concepts/sop/SOP-00123

Returns:

---
type: SOP
doc_id: SOP-00123
title: Equipment Cleaning - Grade C/D Areas
version: 4.2
status: Effective
effective_date: 2026-01-15
review_due: 2027-01-15
owner: Manufacturing QA
site: [Dublin, CA]
product: [Product A, Product B]
regulation_refs: [21 CFR 211.67, EU GMP Annex 1]
resource: /api/v1/qms/documents/SOP-00123/v4.2/pdf
staleness: 2026-07-11T04:00:00Z
training_required: true
risk_level: High
---
# Purpose
Standard cleaning procedure for equipment in Grade C and D areas
at the Dublin facility.

# Related Documents
- [Work Instruction WI-088](/api/v1/okf/concepts/work-instruction/WI-088)
- [Validation Protocol VP-234](/api/v1/okf/concepts/validation/VP-234)
- [Equipment EQ-442](/api/v1/okf/concepts/equipment/EQ-442)
- [21 CFR 211.67](/api/v1/okf/concepts/regulation/21-cfr-211.67)

# AI Guidance
retrieval_priority: high
common_questions:
  - "What cleaning method is required after Product X?"
  - "What is the rinse verification procedure?"
known_risks:
  - "Cleaning validation failures when operators skip rinse verification (Section 3.2.4)"

Notice three things:

The resource field points to the live QMS. If the agent needs the actual controlled PDF — for citation, for verification, for a decision that requires the approved document — it follows the resource link to the validated system, which enforces training requirements and access controls.

The staleness field is a timestamp, not a guarantee. The agent is expected to check this before relying on time-sensitive fields (approval status, effective version). For anything decision-relevant, the agent calls GET /api/v1/qms/status/SOP-00123 against the live system.

The AI Guidance section is separate from regulatory content. Common questions, known risks, retrieval priority — these are AI-specific enrichment fields that help agents reason more effectively. They’re stored separately from the regulatory content and can be updated without triggering change control on the document itself.

The knowledge graph layer

The graph is defined as a property graph over existing relational tables:

CREATE PROPERTY GRAPH quality_graph
  VERTEX TABLES (
    sops LABEL sop
      PROPERTIES (id, doc_id, title, version, status, effective_date),
    deviations LABEL deviation
      PROPERTIES (id, deviation_id, severity, status, discovered_date),
    capas LABEL capa
      PROPERTIES (id, capa_id, status, effectiveness_status),
    equipment LABEL equipment
      PROPERTIES (id, equipment_id, name, location, qualification_status),
    validation_protocols LABEL validation
      PROPERTIES (id, doc_id, title, status),
    regulations LABEL regulation
      PROPERTIES (id, regulation_id, title, framework)
  )
  EDGE TABLES (
    sop_references_equipment
      SOURCE KEY (sop_id) REFERENCES sops (id)
      DESTINATION KEY (equipment_id) REFERENCES equipment (id)
      LABEL references,
    deviation_involves_equipment
      SOURCE KEY (deviation_id) REFERENCES deviations (id)
      DESTINATION KEY (equipment_id) REFERENCES equipment (id)
      LABEL involves,
    capa_closes_deviation
      SOURCE KEY (capa_id) REFERENCES capas (id)
      DESTINATION KEY (deviation_id) REFERENCES deviations (id)
      LABEL closes,
    sop_validated_by
      SOURCE KEY (sop_id) REFERENCES sops (id)
      DESTINATION KEY (protocol_id) REFERENCES validation_protocols (id)
      LABEL validated_by
  );

The graph edges come from the database foreign keys — the same relationships that the QMS already enforces. No hand-maintained markdown links. No LLM-enriched cross-references. The graph is as accurate as the database, because it IS the database, viewed as a graph.

When an agent needs to traverse relationships, it calls:

GET /api/v1/okf/graph/deviation/DEV-2026-102?hops=3

The API runs a SQL/PGQ MATCH query and returns the connected subgraph as a set of OKF concepts with their relationships expressed as markdown links. The agent gets a navigable knowledge graph without ever touching the database directly.

The validation story

This is where the architecture earns the right to exist in a regulated environment.

What gets validated:

  • The PostgreSQL database schema and constraints
  • The API endpoints and their permission enforcement
  • The PDF rendering engine (database → canonical PDF at moment of signature)
  • The OKF serialization logic (database → OKF-shaped response)

What doesn’t get validated:

  • The OKF content itself (it’s a derived projection, regenerated on every request)
  • The agent consuming the OKF responses (it’s reading from a validated API)
  • The AI enrichment fields (they’re advisory, not regulatory content)

This is dramatically cheaper than validating a custom markdown export pipeline. The OKF serialization is a deterministic function: same database state → same OKF output. It can be tested once and trusted. The database is already validated because it’s the QMS.

What the agent workflow looks like

A deviation investigation agent, working within this architecture:

  1. Receives a deviation description from the user
  2. Calls GET /api/v1/okf/concepts/deviation/DEV-2026-102 — gets structured metadata and related links
  3. Calls GET /api/v1/okf/graph/deviation/DEV-2026-102?hops=3 — gets the connected subgraph (equipment, SOPs, prior deviations, CAPAs, validations)
  4. Reads the OKF concepts for each connected entity — gets structured context with AI guidance
  5. Calls GET /api/v1/qms/documents/SOP-00123/v4.2/sections/3.2 — gets the specific procedure section from the live QMS (enforcing training check)
  6. Synthesizes an investigation starting point with full traceability
  7. Presents the draft to a human reviewer, citing every source

Every step is logged. Every document access is auditable. The agent never writes to the QMS. The human approves every decision.

The four OKF principles worth keeping

From the entire debate, four ideas from OKF survived every critique and landed in the final architecture:

1. Concept-per-file (now concept-per-API-endpoint). Each quality entity gets its own self-describing representation with structured metadata and a human-readable body. This is how agents navigate knowledge — one concept at a time, following links.

2. YAML frontmatter as queryable metadata. Every concept carries structured fields that agents can filter on — type, status, version, effective date, tags, site, product. This enables deterministic queries that vector search can’t match.

3. Cross-links as a graph. Relationships between concepts are explicit and traversable. The agent follows the same path a human investigator would — from deviation to equipment to SOP to validation — but through API calls, not file reads.

4. Progressive disclosure via index. The index.md pattern — start with a summary, drill into detail — maps to how agents should consume context. The API serves high-level metadata first, then detailed content on demand.

What the OKF debate taught us

Four blog posts. Two dozen analyses. One convergence.

The debate was never really about OKF. It was about a question that every regulated industry will face in the next three years: how do you make validated enterprise knowledge AI-accessible without breaking compliance?

The answer that emerged — database as truth, graph as relationships, OKF as the agent-facing contract — is bigger than any one format. It’s a pattern for building AI-native enterprise systems in regulated environments. The QMS is just the first application.

The next QMS startup that gets built won’t choose between “validated but opaque” and “AI-friendly but uncontrolled.” It will build both from day one — a validated core that speaks OKF to agents, with a knowledge graph that agents can traverse, and an API that enforces compliance at every endpoint.

That’s not a compromise between the pro-OKF and anti-OKF camps. It’s the architecture both camps were trying to describe.

PostgreSQL 19 SQL/PGQ: neon.com/postgresql/postgresql-19/sql-pgq-graph-queries. ISPE GAMP AI Guide: ispe.org. MCP for life sciences: usdm.com/resources/blogs/the-model-context-protocol-mcp-in-life-sciences.