Kodexa
1 / 16
Architecture

AI document workflow architecture.

How the platform is put together, what each part is responsible for, and what it can prove about its own output.

Arrow keys or click to advance

The questions we get asked

The questions, in the order they usually arrive.

01Where does the record live, and what is actually in it?
02Where does our own expertise live, and who controls it?
03What stops a model from inventing a value?
04What happens when a worker dies halfway through a document?
05What can you show a reviewer, or an auditor, two years later?
06Who runs it, and what happens if we part company?

The rest of this deck answers them in that order.

01 · The shape

Four planes, all inside your tenant.

Your sources Mail, storage, an API, a person YOUR PRIVATE ACCOUNT Control plane One service writes the record, and decides tenant scope for everything else. Process plane The graph, the leases and the retries, held as durable relational state. Compute plane Sandboxes that see one document and hold no lasting credential. Model egress One route out to model providers, with cost and limits enforced there. API Your systems and your people Every resource, under the same access control DATA LAKE Your analytics Open format, partitioned, self-describing Your reviewers work in the graph

Documents arrive from wherever they already are. Everything past that line runs in one private account, and every enterprise customer has their own.

One service is the only writer to the record. Every other component asks it, so tenant scope is decided in one place, and that is the only place it has to be right.

The process graph, the leases and the retries are durable relational state, so a process that is halfway through has a position you can read and report on.

Work executes in sandboxes that see one document, hold no lasting credential, and are handed an identifier they must resolve through the control plane.

There is one route out to model providers, and two doors you use: the API and the data lake. Both are places you can put a control.

02 · The record

The whole record is one file.

A document is one portable, open-format file. The original bytes, the values read out of them and the evidence for each of those values all sit inside it.

ONE FILE The original bytes Exactly the file you sent, kept inside the record The content tree Every word, the box it sat in on the page, and how well it was read The extracted data Typed values, each stamped with whether a model, a rule or a person put it there The definition it was read against The schema travels with the document, so anything downstream can read it without a lookup The audit trail Who changed what, when, under which task, and what the value was before The model ledger Which model was called, on what prompt, for how many tokens, at what cost

Retention, export, legal hold and deletion all act on one thing.

02 · The record

The same engine, compiled three ways.

The control plane Serves the API, writes the record A processing runtime Reads a document, extracts from it The reviewer's browser Opens the file locally ONE COMPILED CORE The document engine Native on the server, linked into the runtime, and compiled to WebAssembly for the browser

A check that passes while a reviewer is looking at it passes identically when the server reprocesses it, because both run the same compiled code, built once and shipped to both places.

A reviewer works against the real document in the tab, not a rendering of it, and a document of tens of megabytes opens and edits there without a round trip per keystroke.

03 · What it knows

Everything downstream is generated from the taxonomy.

Your taxonomy is the business meaning of the work, authored once. The prompt schema and the storage schema are both generated from it, so there is nothing to keep in sync by hand.

AUTHORED ONCE Your taxonomy What the business means by each field, in its own words The schema the model is forced to fill Generated from the taxonomy The typed data the answers land in Validated and audited on the way in What the reviewer sees on screen The same fields and rules, in the taxonomy's order What the API and the lake return Carried inside each document

You author the taxonomy once, in the words the business already uses for these fields.

One generation pass produces all four at the same time, off the same tree, so they cannot disagree with each other. Changing what a field means is one edit to that tree, reviewed as a change to a governed resource, and the same pass rewrites all four.

03 · What it knows

What your team knows, written down once.

Most of what makes a document readable sits outside it: what your team knows about the counterparty, about the layout, about the exception that comes up twice a year. In the platform that knowledge is a resource in its own right, versioned and owned by your people.

YOURS A knowledge set Prompts, examples, lookups, rules Matched to this document By its knowledge features Merged into the document As a new, immutable version Extraction runs Every value can name the item that shaped it A reviewer corrects a value In the ordinary course of work It becomes a candidate Proposed, and waiting on somebody with the authority A person promotes it Into the live set, from then on

A knowledge item is one piece of your operation's expertise: a taxonomy entry, a prompt, a worked example, a lookup row, a rule. Items are grouped into versioned sets, and each set carries an expression over the features content picks up as it moves, so the right knowledge reaches the right content with nobody routing it by hand.

The matching knowledge is merged into the document as a new version before extraction runs. That makes a given extraction reproducible from one artefact, and it means a value can name the instruction that shaped it as precisely as it names the words it came from.

A correction made in the course of review becomes a candidate item. Automation can propose one; a person with the authority promotes it into the live set. Nothing automated writes to a set that is in force, which is what keeps the loop governed as it compounds.

03 · What it knows

A value has to be found on the page before it becomes data.

The model answers A value, and the lines it says it read it from We look again Code goes back to those lines and checks the value FOUND It becomes data Tagged onto the exact words, typed, and recorded NOT FOUND It is withheld Raised to a person, with what the model claimed 184,250.00 p2 · L14 9,410.00 p4 · L07

The schema the model receives will not accept a bare value. Every field has to arrive with the lines it was read from, so an uncited answer is invalid before anything looks at it.

Deterministic code then looks for the claimed value at exactly those lines, converting types as it goes.

If it finds it, the value is tagged onto the exact words on the page and becomes typed data, and the tokens it came from stay attached to it.

If it cannot, the value is withheld; there is no confidence threshold that lets it through. It becomes a work item naming what the model claimed, which lines it cited, and what those lines actually said.

Where a business decides a field needs a looser rule, that is a setting on the field, applied by the person who owns the definition and recorded against the field.

04 · The work

A person is a step, and a decision is an edge.

A model reads A rule runs A person decides Your system An agent
Arrives Intake Classify What is it Extract Read the fields Check Your own rules Review Only what failed, and why it failed APPROVE Posted Into your system REWORK Read again With the correction REJECT Closed With the reason

A process is a graph of typed steps. Each one declares what has to be true before it can run, so the definition fixes the order and any worker that picks the step up honours it.

Human work is the same kind of node. It waits as a row, which costs nothing, survives every deployment, and stays queryable while it waits.

The reviewer's named action decides which edge is taken. Approve, rework and reject are separate paths through the same graph, so the graph itself shows why a document went the way it did.

04 · The work

What happens when something goes wrong.

These are six of the failures we design for, and what the platform does on each of them.

A worker dies mid-document

The work was never held inside the worker. It holds a lease on a row and extends it while it is alive. When the lease expires the work is reclaimed and retried, under the retry policy stamped on it when it was planned.

A message goes missing

Queues carry notifications; the state is in the database. A background pass looks for work that stopped moving and replays the completion, but only once it can prove the underlying work actually settled.

One tenant floods the queue

Every dispatch slot goes to the least loaded tenant by weight, so a large batch cannot take the head of the line. Work that cannot get capacity goes back on the queue and waits, so a saturated system runs slower and keeps its error rate flat.

Nobody reviews it for three weeks

The step is a row with an owner and a status. It costs nothing to leave sitting, it comes through deployments intact, and you can report on it the whole time.

A stage keeps failing

Retry, timeout and backoff are resolved when the work is planned and written onto it, so a configuration change cannot rewrite what is already in flight. A stage can be declared non-fatal, in which case exhausting its retries advances the process to the next step.

A model provider throttles you

Calls retry with backoff behind the one gateway, and every attempt is priced and recorded against the document. There is no automatic failover between providers. If one goes down, someone repoints the gateway by hand.

04 · The work

Code you did not write, run as if you did not trust it.

Extraction logic, third-party modules and agents all execute in the compute plane, and that plane is treated as hostile.

What goes in
  • The dispatch payload names the work and never carries the document. The runtime fetches that itself, through the control plane.
  • The run gets two short-lived credentials. One reads and writes the data for this run; the other reports on this attempt and nothing else.
  • A shared platform credential never enters the sandbox.
What runs
  • The unit of work is one document at one stage, which is also what cost, concurrency and audit are counted against.
  • Deny by default: third-party code gets one scratch directory for a filesystem, and reaches only the hosts its own declaration names.
  • The environment is disposable, so everything that matters is written back through the control plane.
What comes back
  • Each stage produces a new derived document and leaves its predecessor intact.
  • The result is verified against live state before it is accepted, so a worker from an earlier attempt cannot write over the current one.
  • Because every stage left a version behind, reprocessing starts from the last good version.

Extraction and reasoning calls leave through one gateway, which holds the provider credentials, so cost, routing and rate limits are enforced in one place.

05 · The evidence

"Show me why the system said that."

Total184,250.00
  • The value184,250.00, typed as a decimal, with the type it was asserted as when it was written
  • Where it came fromThe words inside that box on that page, and how well they were read
  • Which model read itThe model, the prompt it was sent, its answer, the tokens and the cost of the call
  • Under which definitionThe taxonomy in force at the time, carried inside the document
  • Who has touched itThe reviewer, the timestamp, the task they were working, and what the value was before
  • What came beforeEvery earlier version of the document, back to the original bytes

All of it is in the file, so it inherits the file's access control and the file's retention. Two years later the answer does not depend on a log that has since rolled or a service that has since been replaced.

06 · The estate

One account per customer. We run it.

Every enterprise customer gets a private tenant account in the region they choose. We operate it, and nothing in it is shared with any other customer.

The account

Yours alone, top to bottom

Separate storage, separate database, separate compute, separate model route. There is no pooled tier underneath and no multi-tenant table your documents sit in next to somebody else's.

Two doors

The API and the data lake

Every resource the platform holds is reachable through the API, under the same access control the screen uses. Extracted data lands continuously in the lake in open format, partitioned, carrying the definition it was read against.

Disaster recovery

A second environment, if you want one

Optional private DR: a second environment in another region, kept in sync, private to you on the same terms as the first.

Change control

Schema moves as reviewed SQL

Schema changes ship as versioned SQL applied under a lock at start-up. Nothing in the platform issues DDL of its own accord, which is what makes promotion between environments a reviewable event.

06 · The estate

Where the boundary sits.

We operate the infrastructure. You own the knowledge and the record it produces, and you reach both through two documented surfaces. If your controls need to sit somewhere else, say so now.

Yours
  • The documents and their evidence
    Every version, back to the bytes you sent, with the audit trail inside each one.
  • The definitions and the processes
    What a field means, which steps run, which prompts are used. Authored by your people, versioned in your repository.
  • The extracted data
    Typed, validated, and carrying the definition it was read against wherever it goes.
  • Who holds which role
    You decide who can review, who can approve, and above all who can change a definition, because that is where extraction behaviour is decided.
How you reach it
  • The API
    Every resource the platform holds, under the same access control the screen uses. The screens are built on it, so there is no surface your systems cannot reach.
  • The data lake
    Open format, partitioned, self-describing, updated as work completes. Query it with whatever your analytics teams already run.
  • That is the whole surface
    We keep the infrastructure closed and the interfaces documented, so the boundary is a small number of things to review rather than a running estate to assess.
  • And it is yours alone
    Both doors open onto your account only. No shared index, no shared model tuned on your data, no path between one customer and another.
06 · The estate

What it takes to leave.

Four answers to the exit question. The short version is that everything you would want on the way out is already in an open format, and most of it is already moving.

The documents are ordinary files.

Open format, one per document, carrying its own content, data, schema and history. Our command-line tool reads one and prints all of that with no platform running.

The configuration is text.

Definitions, processes and prompts round-trip to manifests in your own repository, and promote between environments as reviewed changes. Git is the versioning system, deliberately.

The data is already arriving.

Every version lands in the lake as an open, partitioned file carrying the definition it was read against, alongside the audit trail. A document from three years ago still explains itself.

There is one account to hand over.

Because your work lives in a single private account, a handover is a copy of things already in open formats, on infrastructure with one owner.

None of that is a migration path we would build for you on the way out. It is how the system stores things while you are using it.

07 · The age of agents

Your engineers will bring agents. The platform was already shaped for them.

Four properties decide whether a coding agent can be useful against a platform on its first day. They are ordinary properties of a well-built API, and we had them before the agents arrived.

Addressable

Everything has a name

A resource is referred to by a readable URI, never by an environment-specific id, so the same reference means the same thing in your sandbox and in production. Resolution happens server-side, under the same access control as every other call.

Described

The spec is the code

The API description is generated from the source. Every change regenerates it and fails the build if it differs from what is committed, and a route with no entry in it does not merge. An agent reading the spec is reading the running system.

Uniform

Declared once, generated everywhere

One declaration per resource type produces the REST surface, both halves of access control, the audit record and the spec entry together. Seventy-seven resource types go through it, so the surface an agent learns once holds everywhere.

In text

Configuration is a repository

Definitions round-trip to YAML in your own repository, with environment-specific identifiers rewritten to slug references. A dry run puts a change through the server's real validators without writing it, so an agent can check its own work before it asks.

What a spec cannot carry

We publish the rest as a skill pack

A spec says what a valid request looks like. It cannot say which of two valid-looking spellings is the live one, in what order things have to be applied, or how to write a definition a model can act on. So that ships as an installable pack: one skill per resource type, with the shape, worked examples and a mistakes table.

$ claude plugin marketplace add kodexa-ai/kodexa-metadata-skills
$ claude plugin install kodexa-metadata-skills
The obvious question

An agent reads and calls. It does not author.

An agent here runs with no shell, no file write and no outbound network, and that is enforced at the tool boundary by a check that fails closed, not by a system prompt. Its capability is an allowlist per conversation, default deny. Its calls go through the same access control a person's do.

For configuration it drafts into your editor and a person presses Save. The agent-side save tools were removed so that stays structural. A delegated token whose authority can only ever be a subset of the invoking human's, and a staged change a human approves against a content digest, are built and in review.