The data model

Most professional-services software spends its first year rebuilding the same plumbing: a way to track a case, a way to draft a document, a way to keep a client list, a way to send an invoice. Opbox treats all of that as already solved. The substrate ships these as provided primitives so that nobody has to build them again. Your effort goes into the specialist work on top, never into the scaffolding underneath.

This page walks through each primitive in plain terms: what it is, the handful of details you would actually care about, and what you can do with it. Then it shows how they connect into one coherent picture of a piece of work.

A useful mental model: think of a well-run filing cabinet that also knows the rules. Every primitive is a kind of record with a fixed, sensible shape. Because the shape is fixed, both a person and the AI assistant can read it the same way - the structure is the product.

Matter - one unit of work

A matter is a single piece of work with a beginning and an end: a case, a company incorporation, a visa application, an estate. It is the spine everything else hangs off.

A matter you would recognise has:

• A title - what the work is called.
• A status - one of OPEN, ON_HOLD, COMPLETED, or CANCELLED. That is the whole lifecycle: live, paused, finished, or stopped. A finished or stopped matter is closed and locked; the record stays, but it cannot be quietly rewritten.
• A number - a tidy sequential reference (matter 1, matter 2, …) that is unique within your firm. Two different firms on two different boxes can both have a “matter 42”; inside one firm the number never collides.
• Links to its parties, its documents and files, and its bills - covered below.

What you can do with a matter:

• Create one (give it a title; everything else has sensible defaults).
• Advance it - move its internal workflow forward one step.
• Hold it - park it ON_HOLD when you are waiting on the client or a third party.
• Cancel it - close it without completing, with a reason recorded.
• List and read matters, filtered by status.

A matter is also the privacy boundary. A confidential matter is only reachable by people who are allowed to see it; you cannot even probe whether a hidden matter exists by trying to attach things to it. See the kernel for how that boundary is enforced.

Matter step + the matter-step engine

Inside a matter is a workflow - the ordered things that have to happen. Each thing is a matter step.

A step has:

• A title and a type (more on type below).
• A status - one of PENDING (not started), ACTIVE (the one being worked on now), COMPLETED, SKIPPED (not needed this time), or BLOCKED (cannot proceed yet).
• A phase it sits in (steps are grouped into phases, like “Intake”, “Drafting”, “Filing”).
• An assignee - the person or AI agent responsible for it.

Steps come from a board, which is the reusable template of phases and steps. You author a board once (“this is how we do an incorporation”), publish a version of it, and every new matter of that kind is stamped out from that published version. The matter remembers which version it was created from, so improving the template later never silently changes a matter already in flight.

The step kind carries a typed shape

This is the quietly powerful idea. A step is not just a label like “Collect ID”. Each step kind carries a typed shape - a small, structured description of what that step needs and produces. A FORM step knows it collects a form. A DOCUMENT step knows it produces a document. A SIGN_DOCUMENTS step knows it sends something for signature. Because the shape is structured rather than a sentence of prose, the AI assistant and a human read the same description and both know exactly what the step is for. TASK is the plain fallback when a step is just “do this thing”. (The substrate ships a small core set of these kinds; new kinds are added as configuration, not as new code.)

Driving a matter forward

The engine that runs all this is deliberate and safe by design:

• Advancing completes the active step and works out what becomes active next, respecting which steps depend on which. At most one step is active at a time, so there is always a clear “what now”.
• Holding parks the whole matter.
• Skipping marks a step not-needed (an audited override - the record shows it was a deliberate choice).
• A step can be blocked - it cannot start until something it waits on is resolved.

Approval gates inside a step

A step can require an approval gate before the matter advances past it - a deliberate human-in-the-loop checkpoint. “Don’t file this until a partner signs off.” That gate is its own primitive, described further down.

A matter can even spawn a child matter and wait for it to finish before resuming - for the cases where one piece of work legitimately depends on another completing first.

Document vs file

These are two different things, and the difference matters.

A document is structured rich text that Opbox owns and understands. Think of a draft engagement letter, a witness statement, a contract you are editing. Because Opbox understands its structure, a document can be:

• Edited in place, surgically - the system patches the change rather than rebuilding the whole thing, so nothing else on the page is disturbed.
• Versioned - every saved version is kept, so you can see history and restore an earlier one faithfully.
• Generated - drafted from a template with the client’s details filled in. If a required field is missing, generation refuses rather than producing a document with a silent gap.
• Rendered to PDF or DOCX - a downloadable copy. The rendered file is a by-product; the document itself stays the source of truth, so a failed render never damages the original.
• Tracked - turn on tracked changes and edits become reviewable insertions and deletions you can accept or reject, the way a regulated redline works.

A file is a binary blob - an uploaded PDF, a scanned exhibit, a photo of a passport, a signed agreement that came back from elsewhere. Opbox stores it and keeps it safe (the bytes are encrypted at rest) but does not treat it as editable rich text. You put a file in, get it back out, list a matter’s files, and keep a history of versions.

In short: a document is something Opbox can read and rewrite; a file is something Opbox holds intact. Both belong to matters, and both can be attached to one.

Party - a person or an organisation

A party is anyone or anything a matter is about: a client, the opposing side, a company, a director, a shareholder. There is one party primitive with two kinds: a natural person or a legal entity (a company or other organisation).

A party has a plain display name and an ACTIVE lifecycle (it can later be suspended for a dispute, archived, or merged - see below). The sensitive identity details a regulated practice needs - passport numbers, dates of birth, KYC and risk status - live in a separate, encrypted compartment attached to the party, kept apart from the everyday name-and-role view.

Two features make parties genuinely useful rather than just a contact list:

De-duplication. The same person should never quietly exist twice. When a party is identified by something unique - an email, a passport number, a company registration number - Opbox checks for a match using a one-way fingerprint of that identifier (never the raw value), so the same human maps to a single party. When a confident duplicate is found it can be merged; a low-confidence match is sent for human review rather than merged automatically. The losing record is folded in, not deleted, so the trail survives.

Relationships. Parties connect to each other with typed roles: this person is a director of that company, holds 30% of it, is its secretary, or is an authorised signatory; one company is the parent of another. A share percentage rides on the ownership roles. When a director resigns, the relationship is marked inactive rather than erased - the statutory register stays honest.

What you can do with a party: create one, read its profile, set its detail facets, record relationships, run a KYC review, merge duplicates, and suspend, archive, or reactivate it.

Form - collect data, optionally start work

A form is a template that collects data - an intake questionnaire, a client onboarding form, a fact-gathering sheet. Under the hood a form is the same kind of versioned, published template a board is, just authored to ask questions instead of run steps.

When someone fills a form in, that response is a submission. A submission has its own short lifecycle: OPEN (just arrived), REVIEWED, then APPROVED or REJECTED. Each submission keeps an immutable snapshot of exactly what was sent, so the record of “what the client actually told us” never drifts.

The key move: a submission can create a matter. A prospective client fills in your intake form, and that response can open a new matter - pre-populated, with the work already lined up. No re-keying. The form is the front door; the matter is what walks through it.

Bill / invoice / charge

The billing primitives are the money path, and they are built to be exact.

An invoice is a numbered billing document with line items. It carries a contact, a currency, totals, and a status that runs through a clear lifecycle (draft, submitted, authorised, paid or part-paid, overdue, voided). Crucially, “paid” is never something a person sets by hand - it is computed from what has actually been received, so an invoice cannot claim to be paid when it is not. Every money amount is held as a whole number of minor units (pence, cents), never a fragile decimal, so totals are always exact.

A charge mints a hosted pay-now link through a payment rail (Stripe and similar), so a client can pay online. When the money lands, a payment is recorded - and the system is careful never to double-count a payment if the rail tells it twice. Refunds and credit notes are first-class too, with their own lifecycles, and an over-refund is structurally prevented.

Billing can also sync to an external ledger (such as Xero) - and it does so safely: your local copy is always the authoritative one, so if the sync to the outside service hiccups, your data is fresh and correct locally rather than wrong.

What you can do: raise an invoice (often sourcing its lines straight from a matter’s delivered work), transition its status, charge it, record a payment, issue a refund or credit note, and sync to the ledger.

Gate - an approval that must pass first

A gate is a propose-then-approve checkpoint. Someone (or some agent) proposes a change; a human reviews it; only on approval is the change applied. It is the single primitive behind every “needs sign-off” moment in the system, whatever the flavour:

• An internal reviewer approving a change to a matter.
• A client, through the portal, proposing an edit - which is captured as a proposal, never a direct write to your records.
• An AI agent asking permission to take an action beyond its remit.
• A regulated step that needs explicit acceptance before the matter moves on.

A gate has an honest set of states: PENDING → APPROVED → APPLIED, or one of the closing paths (REJECTED, WITHDRAWN, EXPIRED). Notice that approved and applied are different - approving the idea and actually performing the change are two distinct, recorded facts. The proposed change is captured when it is made and replayed atomically on approval, and there can only ever be one live proposal for the same thing at once, so two reviewers cannot approve competing versions.

This is how Opbox keeps a human in the loop exactly where it counts, without sprinkling ad-hoc approval logic across the system.

Entity edges - one graph of relationships

Everything above connects, and the connections themselves are a primitive: an entity edge is a typed, directed link between two things - this file is attached to that matter, this party is linked to that matter, this document belongs to that case.

Rather than scattering a different “link” mechanism into every primitive, Opbox keeps one graph: a single kind of edge that can join a matter, a party, a file, a document, or a table row to one another, each edge carrying a label for what the relationship is (“attached”, “exhibit”, “evidence”, and so on). Linking the same two things twice is harmless - it is the same single edge, not a duplicate.

You attach an entity to a matter with one action - name the matter, name the thing, and the edge is recorded. The safeguard is built in: you can only link things you are actually allowed to see, so the graph can never become a way to peek at records you have no access to. The matter and the thing itself remain the truth; the edge is the connective tissue that lets you ask “what is linked to this matter?” and get a straight answer.

How they fit together

Here is the whole picture in one ordinary sequence. Watch the primitives hand off to one another, and notice that every move is recorded - Opbox keeps an append-only log of who did what, through which door.

1. A new client fills in a FORM. Your intake questionnaire comes back as a submission, with an immutable snapshot of exactly what they told you.
2. A MATTER is created from that submission - opened, numbered, and stamped out from your published board, so it already has its STEPS: the phases and the work, each step carrying its typed shape so the team and the AI both know what each one is for.
3. PARTIES are linked. The client and any companies, directors, or shareholders are identified - de-duplicated against anyone already known - and connected to the matter (and to each other, with typed roles) as entity edges in the one graph.
4. DOCUMENTS are drafted and FILES attached. The engagement letter is generated from a template with the client’s details filled in, edited, versioned, and rendered to PDF. The passport scan and other exhibits are uploaded as files and attached to the matter.
5. A GATE approves filing. Before the matter advances past the critical step, a partner reviews the proposed action and approves it - human-in-the-loop, captured and applied atomically.
6. A BILL is raised. An invoice is created - often sourcing its lines straight from the matter’s delivered work - a pay-now charge is sent, and the payment is recorded when it lands.

At no point did anyone rebuild a case tracker, a document editor, a contact system, or an invoicing engine. Those were the solved primitives. The matter walked from intake to filing to billing, and the whole journey is on the record.

Where to go next

• The kernel - how every action above goes through one verb door, and how the privacy boundary is enforced.
• Agents & MCP - how the AI assistant drives these same primitives.
• The verb reference - the full list of actions you can take on each primitive.