Architecture · v2.0

The kernel, end to end.

AIPROCUREMENT.CLUB runs on three isolated vertical instances sharing one PostgreSQL database, connected by a typed event bus. Agents run as Supabase edge functions. Logic lives in PL/pgSQL constraint triggers, not application code.

01

System overview

Three Next.js 16 instances (P2P :3000, Treasury :3001, MRO :3004) plus ClinKernel and Telecom share the same Postgres 16 with row-level security. The cross-vertical event bus is database-native: typed tokens, immutable once emitted, causation-tracked.

:3000

Procure-to-Pay

14 agents

:3001

Treasury & Revenue

9 agents

:3002

ClinKernel

6 agents

:3003

Telecom Expense Management

5 agents

:3004

MRO / Aviation

in development

event bus signature

-- Cross-vertical event bus (extract)
CREATE TABLE events (
  id           UUID PRIMARY KEY,
  event_type   TEXT NOT NULL,        -- e.g. 'po.created'
  emitted_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  emitted_by   TEXT NOT NULL,        -- agent or actor id
  vertical     TEXT NOT NULL,        -- 'p2p' | 'treasury' | …
  payload      JSONB NOT NULL,
  causation_id UUID REFERENCES events(id),
  correlation  UUID NOT NULL,
  prev_hash    BYTEA NOT NULL,       -- SHA-256 of previous event
  self_hash    BYTEA NOT NULL
);

CREATE INDEX events_correlation_idx ON events (correlation, emitted_at);
CREATE TRIGGER events_immutable BEFORE UPDATE OR DELETE ON events
  FOR EACH ROW EXECUTE FUNCTION raise_immutable();

02

Agent handoff network

Agents are stateless edge functions. Coordination is by event consumption, not RPC. A typical P2P pipeline:

requisition-agent→po-agent→idoc-architect→invoice-matcher→payment-agent

Spawned in parallel for RFQ, surveillance, pricing, and SAP integration. Each agent writes to the event bus; downstream agents subscribe.

03

Data flow table

Event	Trigger	Agent	DB writes	Treasury effect
`requisition.created`	Telegram /req	`requisition-agent`	requisitions, audit_events	—
`po.issued`	requisition.approved	`po-agent`	purchase_orders, idocs	commitment posted
`goods.received`	WMS scan	`goods-agent`	goods_receipts	—
`invoice.received`	email / OCR	`invoice-matcher`	invoices, match_results	liability accrued
`invoice.matched`	3-way match ok	`invoice-matcher`	invoices.state, ledger	payment scheduled
`payment.released`	due date reached	`payment-agent`	ledger_events	cash decrement
`discount.proposed`	treasury float	`pricing-agent`	discount_offers	provisional gain
`dispute.opened`	invoice.disputed	`dispute-arbitrator`	disputes, evidence_hashes	liability frozen

04

State machine registry · 131 transitions across 16 entities

Transitions live in the proc_state_machines table. Adding a new valid transition is a single SQL INSERT — no code deploy.

Entity	Vertical	Sample states	Transitions
`requisitions`	p2p	draft → submitted → classified → approved → po_issued → closed	12
`purchase_orders`	p2p	draft → sent → acknowledged → received → invoiced → closed → cancelled	9
`invoices`	p2p	received → matching → matched → disputed → approved → paid	11
`suppliers`	p2p	onboarding → active → blocked → offboarded	7
`rfqs`	p2p	open → evaluating → awarded → cancelled → closed	8
`workflow_tasks`	cross	queued → running → succeeded → failed → retried	16
`documents`	cross	draft → review → approved → effective → superseded → retired	8
`adverse_events`	life-sciences	reported → triaged → assessed → susar → closed	8
`clinical_trials`	life-sciences	design → enrolling → active → locked → closed	10
`capa_cycles`	life-sciences	opened → root-cause → action → verification → closed	6
`sops`	life-sciences	draft → approved → effective → superseded	5
`transactions`	treasury	posted → locked → reversed	7
`discount_offers`	treasury	proposed → accepted → rejected → expired	5
`mro_aircraft`	mro	active → grounded → in-maintenance → retired	6
`work_orders`	mro	opened → planned → executing → released	8
`disputes`	cross	opened → arbitrating → resolved → closed	5

adding a transition

INSERT INTO proc_state_machines (entity, from_state, event, to_state, requires_evidence)
VALUES ('invoices', 'matched', 'auto_pay', 'paid', true);

05

Database invariants · 19 constraints

Constraints enforced by Postgres, not by application code. Cataloged across four levels.

Level	Invariant	Description
attribute	`positive_quantity`	qty > 0 on every catalog and inventory row.
attribute	`positive_price`	price > 0 enforced at column level.
attribute	`enum_state`	state column constrained to declared enum.
attribute	`iso_currency`	currency ∈ ISO 4217 codes.
attribute	`utc_timestamp`	all timestamps stored UTC, timezone-aware.
tuple	`split_sums_to_total`	sum(line.amount) = header.total per invoice/PO.
tuple	`single_current_version`	exactly one row with is_current=true per logical id.
tuple	`approval_quorum`	every approval row carries ≥1 valid signature.
tuple	`three_way_match_keys`	invoice ↔ PO ↔ GR keys match before paid.
table	`forward_only_state`	state can never go backwards on terminal entities.
table	`immutable_ledger`	ledger_events.append-only; updates rejected by trigger.
table	`immutable_audit`	audit_events table is INSERT-only.
table	`monotonic_versions`	document.version is strictly increasing per logical id.
table	`no_orphan_lines`	every line FKs a header (FK + ON DELETE RESTRICT).
database	`evidence_gated_transition`	state changes that require evidence reject without it.
database	`webshop_fulfillment`	webshop order cannot ship without paid + stock.
database	`price_floor`	no quote below configured floor per category.
database	`sso_domain_unique`	one SSO config per email domain across all tenants.
database	`hash_chain_continuity`	audit head_hash recomputable from prev_hash chain.

06

Workflow invariants (Petri-net theory)

Place invariants are conservation laws over active tokens. Transition invariants prove processes reach terminal states. Verification: proc_check_place_invariants().

9 PLACE INVARIANTS

adverse event lifecycle
analysis cycle
capital deployment
document lifecycle
entity registry
invoice lifecycle
purchase order lifecycle
requisition lifecycle
RFQ lifecycle

8 active

requisitions

3 active

analysis cycles

100%

hash chain integrity

7 TRANSITION INVARIANTS

CAPA completion
market intelligence cycle
requisition rejection path
SOP lifecycle
spawn / close cycle
procurement workflow
SUSAR reporting

07

Technology stack

Framework

Next.js 16 · App Router · 3 instances

Database

PostgreSQL 16 · RLS · pgvector (HNSW, 1536-dim)

Edge

Supabase · 14 edge functions

LLM

OpenRouter · Claude Opus 4.6 · Gemini Flash (OCR)

Integration

Telegram Bot · SAP ORDERS05 IDocs · Slack

CI/CD

GitHub Actions · pgTAP · Playwright smoke

Continue to API reference →