Company Brain Architecture

01What we are building

A Company Brain answers questions and performs work over a company's own operational data, while enforcing that each person sees only what they are entitled to see — decided per request and per field, not per document.

It installs on the client's own server. One deployment serves one company. Departments are filters within it, not separate systems, so adding the ninth department costs configuration rather than a rebuild.

That is the architectural thesis. An agent roster, a visual builder, agents delegating to one another, a browser driving a client's accounting system — each is a permission problem before it is a feature problem. One decision point is what stops those features fighting each other.

What makes it different from a chatbot over documents

• Answers from rows, not just documents. The valuable answers live in a helpdesk, a CRM and a ledger, reached by typed functions.
• Redacts at field level. On one client record, one person sees hours remaining and not contract value; another sees both.
• Acts. Runs multi-step work, drives a browser where no API exists, verifies the result, asks for approval when sensitive.
• Installed, not subscribed. The client holds their own data and their own model keys.

02The full architecture

Every layer, top to bottom. Read this once before anything else; the rest of the document expands each band.

03The Python stack

Decided: Python. It is the better fit here, and the reason is not preference — it is that four of the components this system depends on most are Python-native, and a TypeScript build would have needed a separate Python sidecar container to run them anyway.

What Python changes, and what it does not

Changes. No sidecar — Docling, Presidio, Splink and the eval harness are imports in the same process family. Pydantic becomes the entity-tagged result envelope, which is a genuinely better fit than a TypeScript equivalent because the redaction walker operates on validated models rather than plain objects. And LangGraph is available natively, with its checkpointer and interrupt primitives.

Does not change. The gate, the redaction walker, the tool registry, the leash, the three lanes, the data tiers, entity resolution, the org model, and every diagram in this document. Those are language-independent by design, which is why this decision could safely be deferred until now.

The one thing to budget explicitly

LangGraph's library is MIT, but langgraph-api — the server providing persistence, task queues and crash recovery — is Elastic-2.0 and needs a commercial key in production. We do not use it. The open-source Postgres checkpointer saves state; what it lacks is something to re-drive a thread after a crash. That driver is ours to build, roughly a week's work, and it sits behind the same adapter seam described in §20 so Hatchet or Temporal can replace it without touching the graphs.

One import note: Uvicorn's repository moved from the encode organisation to Kludex/uvicorn. Same package, but pin it and know where upstream lives.

04Core concepts

No term is defined using another undefined term. Read this before any later section.

05The request lifecycle

1. Arrive. The channel adapter normalises and dedupes the platform event.
2. Identify. Channel identity maps to a principal. An unbound identity gets nothing.
3. Entitle. Resolve E(principal), cached 60 seconds, invalidated on any grant write. Compute ent_hash.
4. Intersect the channel. What this channel may carry, and how assured this identity is.
5. Screen. An injection classifier scores the input. It never permits or blocks.
6. Cache. Key = question + ent_hash + agent config hash + policy epoch.
7. Route. FAST, ANSWER or TASK, by deterministic rules.
8. Choose the agent. Channel binding, then rules, then a cheap classifier. The user does not pick.
9. Project the catalogue. agent grants ∩ E. A tool the caller cannot use is absent, so there is nothing to jailbreak toward.
10. Loop. The model reasons, calls tools, loads skills, retrieves knowledge, consults memory.
11. Check the leash before every call. Shadow simulates; Assisted renders the real artefact for approval; Autonomous proceeds.
12. Redact. Walk the typed result depth-first; delete every field not in the caller's mask; drop anything untagged.
13. Trace the post-redaction payload only.
14. Answer, with citations carrying freshness and a trace reference.

Steps 1 to 9 all happen before any model runs. The result contract that makes step 12 possible:

{"@entity":"client","@id":"c_123","hours_remaining":12,"contract_value":48000,
 "tickets":[{"@entity":"ticket","@id":"t_9","subject":"…","internal_note":"…"}]}

06Company, departments, users

Company → Departments → Users, exactly as you described. Agents exist at three visibility levels.

This is the single most important rule in the permission model, and it is worth knowing that two shipping products do the opposite. Notion's Custom Agents documentation states an agent "responds using the agent's own access, not the permissions of the person who triggered it". Dust states an agent "inherits the access right to the data that has been used… independently of who uses the agent".

Under our model a Super Admin can publish a company-global agent that reaches finance tools, and a junior invoking it still sees only what that junior is entitled to. That makes cross-department agents safe to publish globally, which the creator-inherits model forfeits. It is a competitive advantage as much as hygiene.

Formally: E_run(caller, agent) = E(caller) ∩ agent_ceiling. The agent id is not an argument to the entitlement resolver, not in the cache key, and not visible to the redactor. The ceiling can only shrink an already-computed set.

07Roles and permissions

Two separate tables answering two separate questions. Roles govern the platform — publish, install, appoint, read audit metadata — and are a compiled constant, not editable rows. Entitlements govern data as (capability, scope) pairs. No role implies a capability, including Super Admin.

Deliberately not roles

Three planes of visibility

Oversight and data access are different things, and separating them is what lets a Super Admin do their job without becoming a universal reader.

A Super Admin can grant themselves a capability — refusing that would just push people to the database — but doing so writes a loud audit event and notifies the object's steward. The Auditor role exists so that action is visible to someone who cannot perform it.

The mover case is where permission systems actually leak. When someone changes department: entitlements re-resolve on the next request automatically; personal agents follow them; their delegations are re-evaluated and any that would now exceed their entitlements are suspended, not silently narrowed; cached answers keyed on their old ent_hash become unreachable by construction; and memories tagged with the old capability set stop being replayed.

08Data: what we store

Confirming your question directly: we do not sync connector data. With one deliberate, bounded exception, described below, because pure federation is arithmetically impossible.

The projection is roughly 40 MB at your scale, against tens of gigabytes for a mirror. Email, phone, NRIC, bank details and salary are on a permanent deny list with no exception.

Why the projection has to exist

A realistic question touches 5–20 records. Federating everything means 15,000–60,000 calls a day against a Xero ceiling of 5,000. Separately, Freshdesk's search returns at most 300 records ever, so "which clients have an open P1 older than five days" has no live answer at any speed. Headers must be local; bodies never are.

Never store a resolved ACL. Store the source's visibility predicate and evaluate it against the live entitlement set. When someone changes department, the next query returns a different row set with zero writes and zero invalidation. Microsoft's own connector docs admit their incremental crawls do not update permissions at all; Glean's full crawls run on 28-day cycles. This is where the category fails and we do not.

The rule for a new field: if the fast lane must filter, sort or count on it and the source will tell us when it changes, project it. Otherwise fetch it live. No change signal means no projection — that clause is what stops the projection becoming a mirror.

09Entity resolution

You identified the hardest problem in the design. "ABC" in Xero, "ABC Pte Ltd" in the maintenance portal, "ABC Pte" in HubSpot. The same for people and projects, and one client may legitimately have several names.

This is not a nice-to-have: the entity registry is the join key that makes federation possible at all. Without it the system cannot know which Freshdesk company, which Xero contact and which Laravel row are one organisation, so it cannot fetch the right record live. It is why the registry sits in the LOCAL tier.

A cascade, strongest evidence first

The scoring is Fellegi-Sunter: each field contributes a weight reflecting how reliably it agrees on true matches versus how often it agrees by coincidence. That gives two thresholds rather than one, and the band between them is the review queue — it falls out of the model rather than being bolted on. It also gives the reviewer their explanation for free: "same web domain, strong; similar name, weak; different phone, negative".

Three specifics that matter for Singapore. A free-mail domain like gmail.com must be blocklisted, not merely weighted low, because it agrees constantly by coincidence. Phonetic matchers such as Soundex are English-centric and documented as unreliable on multibyte text, so they are actively harmful on romanised Chinese, Malay and Tamil names — use edit distance and the Daitch-Mokotoff variant instead, weighted low. And trigram similarity is unstable on very short strings, so anything under four normalised characters goes straight to review.

Merges must be reversible, unlike every CRM

Salesforce cannot undo a merge. HubSpot states plainly that records cannot be unmerged. Both destroy the pre-image, which is why a small industry exists to recover from it.

We can do better cheaply, because we never own the source records — the registry is a mapping layer over immutable source ids, so a merge moves pointers only. Every merge writes the complete prior state of the affected links and aliases into an append-only decision row first. That single column turns unmerge from impossible into an update. A canonical id, once issued, resolves forever through a forwarding pointer, so an old memory citation never dangles.

Guardrails, and what happens when it cannot decide

• Blocked values. Known junk — test entries, placeholder domains, shared mailboxes — can never cause a link.
• Per-identifier caps. A limit on how many distinct values of one identifier type may attach to an entity, which catches runaway merges before they cascade.
• Priority order. When two candidates collide, which identifier wins is configured, not accidental.
• Money boundary. A merge that would join entities with financial records never auto-links, regardless of score.
• Unresolved is stated, never guessed. The agent says "I can see an ABC Pte Ltd in Xero and an ABC in the maintenance portal and I have not confirmed they are the same company", and offers the review link. It does not silently pick one, and it does not merge the numbers.

The resolver holds hashed join keys rather than full records — roughly 7 MB of non-reversible keys for 60,000 links, against 80 MB of live personal data if we synced contacts. Tooling: Splink (MIT, actively maintained) run offline as a weekly job to calibrate the weights, with the weights exported as a small table and the same arithmetic evaluated online in plain SQL using pg_trgm and fuzzystrmatch. That keeps a Python ML dependency out of the request path and keeps online scoring around a millisecond.

10Knowledge and RAG

Two retrieval planes over one Postgres.

The row plane reaches business records through typed tools whose column projection is compiled from the caller's capabilities before the query runs, so a hidden field is never in the SQL and never crosses the socket. No model ever writes SQL — an LLM authoring queries against a business database defeats any column policy.

The document plane is hybrid search over knowledge and assets: Postgres full-text and pgvector fused by rank, with the scope filter inside the query so out-of-scope rows are absent rather than ranked lower. Assets flow through parsing (Docling, layout-aware so tables in PDF contracts survive), chunking, embedding, and indexing.

This sits directly on the scope primitive and fails quietly — the answer is just thin and nobody files a bug. Either enable hnsw.iterative_scan explicitly, or at these corpus sizes use a partial index per scope, which removes the failure mode instead of tuning around it.

Citations for a row cite the record and the field — "Acme, hours remaining, read 14:02" — because a link to a record does not say which cell the number came from. Every knowledge row carries verified-by, verified-at and review-by, surfaced as a badge, with a scheduled job opening re-verification tasks.

Who can reach which knowledge

Everything uploaded — SOPs, price lists, package definitions, brand guidelines, contracts, meeting notes — lands in one knowledge layer. There is no second store per department. What differs is the scope predicate attached to it, and that is what decides who reaches it.

Without that rule every upload silently widens the company's exposure, and within a year nobody can say why the whole company can read a client contract.

One correction worth making precisely

It is right that the company-level brain holds all the knowledge — there is one store and one index. It is not right that a company-level agent has access to all of it. Access is never a property of the agent; it is always the intersection with the person asking, per §6.

So a global "Company Assistant" published to all 126 staff is safe precisely because it has no standing authority. Someone in Web asking it about a Finance SOP gets nothing, or gets the parts they are entitled to, with the rest shown as locked fields. The same agent asked the same question by the Finance Director returns the full answer. One agent, one knowledge layer, different answers, and no configuration needed to make that true.

Two consequences worth designing for. Pricing and packages are a field-level problem, not a document-level one — a price list usually carries cost and margin columns beside the sell price, and the whole company needs the sell price. Classify those columns rather than restricting the document, or you will end up with three near-identical price lists and two of them stale. And knowledge inherits the mover case: when someone changes department, the department knowledge they could read stops resolving on their next request, with no reindex and no cache purge, because the scope predicate is evaluated live.

11Agents and templates

Templates are how every agent exists — a hand-built one is an instance of the blank template. One code path, one config document, one upgrade story. A template is signed, versioned and immutable; an installed agent is a pinned reference plus an overlay, with per-path ownership tracking who last set each field.

A manifest declares required capabilities; it never grants them. Five paths are sealed by a database constraint: capabilities, leash ceiling, egress, connector auth, and the surface flag. The worst a malicious template can do is ask for a capability nobody holds, and then its tools are simply absent.

Install proves it works. The wizard runs the template's golden set through the real gate twice — once as the installing admin, once as a deliberately low-privilege fixture user — catching both installed-but-dead and works-for-the-admin-only. Missing connectors do not block install; the agent pins to Shadow with an amber badge, and an empty catalogue raises a hard error rather than letting the model answer from general knowledge.

The web agency catalogue

Ship four on day one — Internal Helpdesk, Site Health Sentinel, Support Ticket Agent and Project Status Reporter — because they have the cheapest connectors and produce visibly correct answers immediately. The role templates land in stage 2 once their skills exist.

Three carry a manifest-level Shadow pin regardless of promotion criteria. AR and Renewal Chaser and Accountant Agent because they touch money, and the Accountant additionally because reconciliation errors are found weeks later rather than immediately. SEM Agent because ad spend is the one place an autonomous mistake bills you by the hour — it reads and drafts, and a human commits every budget change. SEO and SMM are read-and-draft by default too, with publishing as a separate grant.

Agents that learn. Learning writes to a reviewable delta queue — typed, evidenced, marked machine-authored — so what an agent taught itself stays permanently separable from what a client configured. A department lead approves or rejects. Nothing changes silently.

12Skills, tools and connectors

Connectors support four transports, all normalising to the same entity-tagged typed contract, so the transport is invisible above the connector layer:

• MCP server — preferred where one exists; hundreds already do.
• REST / OpenAPI adapter — a spec plus a field-mapping file. No code for a well-behaved API.
• Database adapter — read-only credential against allowlisted views only. This is how the Laravel MySQL app connects.
• Custom code adapter — a sandboxed module for anything odd, including legacy SOAP or a scraped portal.

Two properties enforced regardless of transport: scope at connect (one Drive folder, not the whole Drive) and read-only by default, with write as a separate deliberate grant shown at connect time. Every tool declares whose identity it runs as — the requester's by default. Third-party servers are pinned by a hash of their full manifest including tool descriptions, so a silent redefinition fails closed on reconnect.

Skills import in a non-executable state until a named reviewer approves. Progressive disclosure keeps cost down: the agent sees names and descriptions, loading full instructions on demand. A skill's scripts run through one tool, run_skill_script, carrying the sandbox, the leash and output redaction like any other.

13Memory

Build the entity registry first — deterministic, no model, and most of what staff mean by "it remembers". Two invariants: every memory carries the capability set that formed it and is re-checked at read time, so a fact learned by someone who could see contract values is never replayed to someone who cannot; and nothing is promoted to a wider scope without a human. Memory is never authoritative over the database.

Adopt no memory product. Mem0, Letta and Graphiti all partition by id and call it access control, and most drag in a second stateful database. Nothing third-party sits between the capability set and the row.

How an agent actually learns

Not by fine-tuning, and not by writing to itself. But most learning is automatic. An earlier draft of this document required a human for everything, which is wrong: an approval queue nobody has time to work means no learning happens at all, and the control gets bypassed rather than followed.

Notify, do not ask. Tiers 1 and 2 produce a weekly digest — "here are the eleven things the Maintenance agent learned, and what each was based on" — with one-click undo on any of them. Reading a digest and reversing one item is a fraction of the work of approving eleven, and it keeps the oversight.

The review queue has a budget. If tier 3 exceeds a handful of items a week, the thresholds are wrong and the fix is tuning them, not asking humans to work harder. A queue that grows is a design signal, and the console charts it.

Nothing here relies on someone being diligent, because the decay, contradiction and source-truth rules below mean a bad automatic item corrects itself without anyone acting.

What is observed. Explicit thumbs-up feedback is close to dead in internal tools, so the signals are implicit and captured from day one — which makes this a schema decision in stage 1, not a feature to add later:

What gets learned is three different things, and separating them is what keeps this safe:

1. Entity facts. That a client name, a domain, a Laravel row and a helpdesk company are one organisation. Deterministic, highest value, and it lands in the entity registry rather than in memory. Most of what staff mean by "it learned" is this.
2. Procedure. "When someone asks about hosting expiry, check domain expiry too — they are almost always asked together." This becomes a proposed diff against a SKILL.md file, reviewed and versioned like code, not a hidden weight.
3. Preference. "This person wants figures, not prose." User-scoped, never shared.

Does learning go away?

Yes, four ways, and this is deliberate — a system that only accumulates becomes confidently wrong about a company that has moved on.

• Decay. A memory not reinforced loses confidence on a schedule and eventually falls below the retrieval threshold. It is not deleted — the audit record stays — it simply stops being surfaced. Reinforcement resets it.
• Contradiction. A newer observation that conflicts supersedes the older one, which is marked superseded rather than removed, so you can always see what the agent used to believe and when it changed.
• Source truth wins immediately. If a memory says a contract is worth one figure and the source system says another, the source wins and the memory is demoted and flagged for review that day. No decay period.
• Entitlement expiry. A memory carries the capability set it was formed under. When someone's entitlements change, memories formed under the old set stop being replayed for them — no purge job, it simply stops matching.

Promoted knowledge also carries a review-by date, with a scheduled job opening re-verification tasks. A review date nothing reads is documentation, not a control — which is the same mistake as a circuit breaker with no scheduled caller.

Where a person sees and controls it: every agent has a Memory tab listing what it has learned, with the evidence, the confidence, the date and a delete button. A department admin sees the same for their department. Nothing is learned that a person cannot read back in plain language, and anything deleted there is gone from retrieval immediately.

14Multi-agent execution

A large task splits into subtasks, runs across agents in parallel, and merges into one answer. The discipline is in deciding when.

The model proposes; arithmetic decides. A deterministic partitioner builds a dependency graph — node weight is estimated cost, edge weight is shared context a split would duplicate — and a gate decides in pure arithmetic whether parallel beats serial. Fail any condition and the run collapses to a single loop, which is the default rather than the exception. Published measurements put naive fan-out at 1.4–1.6x cost for noise-level gains, and your own prior system measured 2.15x.

Every subtask carries a contract — objective, output schema, tool hints, scope predicate. A result that does not validate is a failed step, not a merge input. Necessary here because the redactor only works on typed data, so "return prose" is not a permitted subtask contract.

Delegation only narrows. A child's grant is computed in SQL as parent ∩ agent ∩ subtask, and a database trigger rejects any delegation row that is not a subset of its parent. The orchestrator has no verb for granting. Depth is capped at two; concurrency at eight per run.

Cross-department work falls out of the scope model: if the asker holds both scopes it is one plan with two filters; if they hold one, they get what they are entitled to plus a stated reason for the gap and a request-access route.

15Browser and computer use

This is a core capability, not an optional extra. Agents navigate, log in, read the screen, fill forms, take multi-step decisions, verify the result and report back — on the many client systems that expose no usable API. Python strengthens this rather than compromising it: Playwright's Python binding is first-class and identical in API to the Node one, and browser-use, the most-starred browser-agent project in existence at 112,000 stars, is Python-native. The credential-injection pattern we adopt in §15 comes from reading its source.

That asymmetry between reading and writing is the reason for the staging, and it also offers a way to have the capability sooner. Read-only browsing can land in stage 4 or 5 — checking a client portal, reading a dashboard no API exposes, pulling a status page — because at roughly 70% success a failed read costs a retry and nothing else. Writes stay in stage 6 behind the full envelope, enforcer and verifier, because a wrongly-reported success corrupts a client's records. If browser work is a priority for you, splitting it that way gets the useful half early without shipping the dangerous half unguarded.

Three planes. A control plane holds the plan, the capability set and the target registry, and never reads a byte of page content — the component that can widen permissions cannot see the text that would ask it to. An untrusted runner in an ephemeral sandboxed container reads the page and holds no authority. A deterministic guard between them contains no model at all: policy compiled at container start and immutable after, an egress proxy the container cannot route around, credential leases, and a hash-chained audit.

The human approves an Envelope once — the plan and its declared writes, rendered as a readable diff in a Lark card — not step by step, which trains people to click through. Re-interruption happens only on envelope breach.

Four supporting mechanisms: the agent reads the accessibility tree, not screenshots (cheaper, less brittle, and a screenshot of a login page can contain the credential while an accessibility node cannot); credentials resolve by reference at the execution boundary, bound to the current origin, never entering a prompt or a log; egress is default-deny to the envelope's origins; and success is never the agent's own claim — a verifier builds its rubric from the goal before seeing the trajectory.

One rule removes most of the risk: the skill loader refuses to register a browser skill for any domain that has a registered API tool, unless the folder carries an explicit exception with a named approver and an expiry. Never attach the agent to a staff member's own logged-in browser profile.

16Channels

Lark, Slack, Teams, WhatsApp, Telegram, a web widget, email and the API — one brain behind all of them. A gateway terminates each platform's wire protocol and does nothing else: no entitlements, no redaction, no policy.

Identity binds outward only. A nonce minted inside an authenticated web session is presented on the new channel. Never a code sent to a number that asked for one.

The group-chat problem is solved by moving when redaction runs. Keep the answer typed and unredacted briefly, then run the redactor at render time under each viewer's own entitlements. Every room gets a room envelope computed at the floor of everyone present, plus a per-viewer body delivered by whatever private mechanism the platform supports — Lark ephemeral cards, Slack ephemeral posts, Teams per-user refresh, and finally a link into the web app where the gate re-runs under the viewer's own session.

Async task results re-run the entitlement computation at send time. A task that takes twenty minutes outlives the world it was authorised in. Per-channel policy decides which sensitivity classes a channel may carry at all.

17Models and routing

Tier, then an ordered chain, then a pinned deployment. Tier classification is deterministic — tool count, estimated context, lane, explicit user request, and whether the scope touches data with a residency rule. Never a model call, because that adds a round trip to every request and would let text inside a retrieved document influence which jurisdiction handles it.

Each attempt appends a row, so the executed chain is reconstructable from one join. The breaker is a fail ratio over a window, not failures per minute — at 0.1 requests per second a per-minute threshold is nearly unreachable and a dead provider stays in rotation for an hour. A background prober keeps an idle-but-broken provider visible. Cooldown backs off with jitter. Alert on fallback depth, not final failure.

Residency is a hard rule: a scope carrying a residency constraint cannot route outside it, and the chain skips those rungs rather than degrading quietly.

18Builder and console

Verz Studio lets a department admin or member create agents without code. Agent authoring is a form composer — identity, persona, knowledge, skills, tools, leash, tests — because control flow is model-driven at run time and the catalogue is projected per request, so an edge someone draws is a promise the runtime would have to break.

The canvas survives where it earns its place: a read-only trace graph of what actually happened on a completed run, which is what people usually want a canvas for, and a bounded procedure canvas that authors a SKILL.md with a small node set, scope predicates as the only conditional grammar, and no code node.

Rehearsal runs a draft against the real gate, leash and redactor, with tool calls replaying recorded fixtures so a test never fires a real side effect. Publish is gated by system-authored permission canaries; author-written tests stay advisory so the gate cannot decay into a rubber stamp. Widening grants demotes to Shadow and needs a second approver; editing instructions does not.

What open source the builder actually uses

A fair challenge, and the answer is that we use a great deal of it — at the library level rather than adopting a whole builder product. All verified 4 September 2026.

The install wizard and every template configuration screen are generated from the manifest's JSON Schema rather than hand-built, which is why adding a template field costs no frontend work. That is react-jsonschema-form doing the job an entire in-house form framework would otherwise do.

Langflow versus building the composer: the full comparison

Langflow is MIT, 154,000 stars and pushed daily. The question deserves a real answer rather than a preference, because adopting it would visibly save frontend work.

The disqualifying detail, in their own words

This is not caution on my part. Langflow's own security documentation states:

• "Langflow neither enforces isolation between users within a single Langflow process, nor restricts access to the local disk or network resources."
• "Flow visibility and user access controls are designed for usability, not security enforcement."
• Its UI ships a code editor that executes arbitrary Python "with full access to the host Langflow backend process, filesystem, and network".

For a product whose entire value is field-level permission enforcement, adopting a builder whose vendor says its access controls are not security controls is not a trade-off — it is a contradiction. A department admin who can write Python in a flow reads the database directly and the gate never runs. Note also that its unauthenticated remote-code-execution flaw in 2025 was actively exploited in the wild, which is what that architecture makes possible.

Disabling code components is possible, but it removes the feature that makes Langflow worth adopting, and leaves you operating a large application for its canvas alone.

The honest concession: our composer is less flexible. Someone who wants a genuinely custom graph cannot draw one, and the bounded procedure canvas only partly covers that. If a client's requirement is "let our people draw arbitrary automations", that requirement is real and the answer is the hybrid below rather than pretending the form covers it.

Where a canvas does belong

Deterministic automation — a trigger, then steps, with no model deciding control flow — is exactly what a canvas is good at, and it carries none of the objections above because the flow calls our tools through the API and the gate still runs on every call.

So ship it as an optional container, sandboxed with allowlisted egress and no database credentials, on the extension-point list so it is a configuration choice rather than a fork. For that job Activepieces (MIT core) fits better than Langflow, and n8n is available where a client already runs one.

The division that results: model-driven agent behaviour is composed in a form, because a drawn edge would be a lie about what the runtime does when the catalogue is projected per request. Deterministic automation is drawn on a canvas, because there the drawing is the truth.

Console, thirteen screens

The console is an ordinary client of the gate: its reads are tool calls with required capabilities, its rows are entity-tagged so the redactor applies to reports as to answers, and a report's audience is intersected with the caller's scope, never unioned. Super Admin filters by department and user; Department Admin sees the same shape bounded to their scope.

Two stores split by classification — a metadata ledger in Postgres with long retention and no content, and a payload store for thirty days behind a separate role with an audit row written before every read. Because the console holds no payloads of its own, observability cannot become a bypass around redaction. Honest counting is enforced in the type system: every request declares its traffic class at ingress with no default, so a new channel cannot compile without saying what kind of traffic it produces.

Three surfaces, not one console

The console is not the whole product, and a screen inventory written late is a screen inventory that gets built twice. There are three authored surfaces plus the chat channels, and they differ by who signs in rather than by what they can reach — entitlement decides that identically in all four.

The two admin roles share one console build with a scope filter rather than two products. A Department Admin's console is the Super Admin's console with the scope chip pinned and the cross-department rows absent — which is a query predicate, not a second frontend. Knowledge and Learning appear in both: a Department Admin sees their own department's rows, the Super Admin sees every row in the company, because coverage across departments cannot be judged from inside one of them.

One distinction the console must hold and most products collapse: a Super Admin sees the complete inventory by role — every item, its owner, scope, freshness and audience. Opening the contents of another department's document is a separate capability, granted by default in a single-tenant install, revocable, and written to the audit ledger on every use. Existence, configuration and content are three planes of visibility, and role governs the first two while entitlement governs the third.

An agent is a container, not a configuration row

The member application and the agent workspace were both missing from the first console specification, and the second omission is the more expensive one. An agent composes eleven things, each stored as a reference with a pinned version rather than an inline copy, so a fix reaches every instance when someone promotes the version and a repository push on its own changes nothing that is live:

Availability and ceiling are two blocks that must never merge in the interface. Availability answers who can find and invoke this agent; the ceiling answers what any run of it may reach. Adding a department to Availability lets forty more people find the agent and gives them no data they could not already reach, because a run still resolves to E(caller) ∩ ceiling. Notion and Dust both ship the opposite — the creator's access travels with the agent — and the reason it is worth building the harder way is that theirs turns every shared assistant into an access-escalation path. The workspace therefore carries a preview-as-a-person control that runs the real gate rather than an estimator, because a preview with its own logic is the component most likely to lie.

Artifacts: what the agent produced

Knowledge and assets are inputs. Until now there was nowhere for output to live — every generated report, deck, export and image had no home in the model, which is a gap AnyGen's interface makes obvious by having solved it. An artifact is not a sixth governed noun, because nobody is granted one; it is an object class with a single rule. An artifact inherits the entitlement of the run that produced it. Field-level redaction is applied at production time rather than at read time, so an artifact can never contain more than its caller could see, and re-downloading re-checks the requester rather than trusting the original link. Retention follows the classification of the most sensitive input that fed it. Artifacts are superseded and archived, never edited, so provenance stays intact.

19Feature list

20Technology decisions

By layer, so every band in §2 has a named component. Health verified 4 September 2026.

Rejected: LLM Guard, MinIO, Daytona and Flowise (all archived, all still widely recommended); Redis and Zitadel and ParadeDB (licence); E2B (needs a cloud account plus Nomad and Consul for ten concurrent requests); Mem0, Letta and Graphiti (partition by id and call it access control); Onyx, Dust and AnythingLLM as a base (all enforce at document level — retrofitting field-level redaction is a rewrite wearing a fork's clothes).

On LangGraph specifically: the library is MIT and excellent, but langgraph-api — the server providing persistence, queues and crash recovery — is Elastic-2.0 and needs a commercial key in production. If you choose Python and want LangGraph, budget building that driver over the open-source checkpointer, and keep the tool registry in one place both the graph and the redactor read.

21Infrastructure

Two Postgres pools, not one. PgBouncer in transaction mode for the app, and a separate session-mode pool for the job worker, because transaction pooling breaks the LISTEN/NOTIFY the worker depends on. Set autovacuum_work_mem explicitly or autovacuum workers inherit maintenance_work_mem and multiply it.

Latency budget. Fast lane under 1.5s, realistically 5–15ms. Answer lane under 8s with one live fetch on an 800ms timeout. Singapore to a source API is 200–600ms before their processing. Provider SDK defaults left alone can be a 10-minute timeout with 2 retries — override to 25s and 1 retry on the answer lane.

What breaks first, in order: document parsing memory during bulk ingestion, Postgres connections, then tracing. None of them is request throughput.

Deployment profiles. Lite is one box for a 50-person client: Postgres, app, worker, Caddy, Keycloak, ledger only. Full adds tracing, payload store, object storage, browser runner and automation. Same code, different compose file.

22Making it faster and more flexible

Additions, not removals. Ordered by impact against effort at your current volume.

Two caches are forbidden by construction. Semantic answer caching, because similarity is not entitlement equality. And any cache keyed without the entitlement hash.

Flexibility comes from four seams: sixteen versioned extension points so a new connector or channel ships without a core release; every vendor behind our own adapter so swapping costs one file; configuration as data in Postgres rather than code, so tuning is not a deploy; and deployment profiles so the same code runs lite or full.

The honest ceiling. Tool and database time was 2.4s against a 27.9s median — 8% of the budget. At a 6s target it becomes 40%. Every model-side lever above stops mattering at that point, and what attacks it is the projection, the fast lane and parallel tool execution. That is the real limit of this design, and it arrives long before request throughput does.

23Hosting, delivery and recovery

Any VPS. Not AWS specifically.

This is Docker Compose on Linux. Hetzner, DigitalOcean, Vultr, Linode, OVH, a local Singapore provider or the client's own hardware all work, and none is meaningfully better than another for this workload. AWS works too if the client is already there, but it is more expensive for the same specification and the client-hosted premise means you would not be using the managed services that justify its price.

Three things matter more than the provider:

• Region. Singapore, for PDPA comfort and for latency to source APIs. A box in Frankfurt adds 300ms to every Freshdesk call.
• NVMe, not spinning or network storage. The database is the whole system.
• /dev/kvm, if you want to promise kernel-level sandbox isolation. Most budget VPS plans do not expose nested virtualisation. Without it, gVisor still works and is what we default to; Kata is the upgrade that needs it. Check this per client before promising anything about isolation.

Cloudflare: useful, not required

Caddy handles TLS automatically, so nothing is blocked without Cloudflare. It earns its place in exactly one case and is unnecessary in another.

One consequence to document rather than discover: with Cloudflare in front, TLS terminates at their edge. For a client with a data-residency clause, confirm that is acceptable before enabling it.

You already have Coolify, so use it

Coolify is Apache-2.0, actively maintained, and covers a real slice of this. It changes three decisions in this document.

Two caveats worth knowing before you rely on it. Coolify's own documentation advises against running it on the same server as the workloads it manages, because heavy application load can starve the control panel — for your own install that is a judgement call, and for client installs it is an argument for Coolify managing them remotely rather than sitting on each box. And budget its footprint: roughly 2 GB for a single application, 4 GB alongside databases, which comes off the figures in §21.

GitHub to server, pull not push

One private repository. GitHub Actions runs lint, type checks, tests, a migration check and the permission canaries, then builds and signs a container image and publishes it to a registry.

That single choice removes the two worst outcomes in a multi-client deployment pipeline: a compromised CI account reaching every client's server, and a client's secrets sitting in a repository. Each install runs a small agent that polls the registry for the tag it is pinned to and applies the update with drain.

The install checklist exists because a copied deployment silently carries four things: platform project files, temporary CLI state, git remotes, and scheduled jobs. Every one of those has caused a production incident in this codebase's predecessor. They are checked on every install, not remembered.

Backup and recovery as a module, not a cron job

The part everyone skips, and the reason this is a module: a weekly job restores the most recent backup into a scratch container, runs migrations, executes a smoke query and a permission canary, records the elapsed time as the measured RTO, then destroys the container. A backup that has never been restored is a hope, and the elapsed time is the only honest answer to "how long would recovery take".

The console's recovery panel shows last backup, last verified restore, measured RTO against the profile's target, and offers a one-click drill. It alerts when backup age exceeds the RPO for that profile, or when a verification fails — which is a louder alarm than a failed backup, because it means the backups you have may not work.

24Quotas, budgets and cost control

A user can build an agent that fans out, calls six tools, retrieves forty chunks and runs on the heaviest model. Nothing in the design so far stops them running it two hundred times. Budgets and concurrency are the same subsystem, so they are specified together.

The budget hierarchy

Every level is a row, editable in the console, versioned and audited. None is a constant in code.

Enforcement happens twice, before and after

Before: the router estimates a request's cost from its lane, tier, expected tool count and retrieval size. If the estimate exceeds any remaining budget in the chain, the request is refused or degraded before a token is spent. After: actual usage is recorded against principal, department, agent, model and lane. Estimates are compared to actuals and the estimator is corrected, because a cost control based on a bad estimate is theatre.

On breach, degrade rather than fail wherever it is safe: drop to a cheaper model tier, then disable fan-out, then queue the task lane, then refuse with a message naming which budget was hit and who can raise it. A hard refusal on the first breach makes people distrust the system; silent degradation without telling them makes them distrust the answers. Say which one happened.

The expensive-agent problem, specifically

An agent's cost is designed in when it is published, not when it is run, so that is where the control belongs. The publish gate in §18 shows a measured cost per run from the rehearsal fixtures — not an estimate — and publishing an agent whose median run exceeds the department's per-run ceiling requires the Department Admin's approval. Fan-out is a separate grant: an agent may not spawn parallel workers unless explicitly permitted, because that is where a single question becomes fifteen model calls.

What the console shows

• Spend by department, user, agent, model and lane, for any period, with machine traffic excluded and labelled as such.
• Cost per answer, and the distribution rather than only the mean — the tail is what surprises people.
• The most expensive agents and the most expensive question shapes, which is the input to the fast-lane roadmap.
• Budget consumption against pace, so a department can see on the twelfth that it is on track to exhaust the month.
• Every refusal and degradation, with which budget caused it.

Because the client holds their own provider keys, these numbers are theirs and reconcilable against the provider's own invoice. That is a genuine advantage over any credit-based hosted product, and worth stating in a proposal.

25Capacity, failure and SLOs

An independent review made a fair criticism of an earlier draft: it was stronger on the security control plane than on operational resilience. That is accurate. This section closes it, and most of what follows is adopted from that review.

Admission control

The design had per-run limits — eight concurrent subtasks, depth two — and no global limit. Twenty users each running eight subtasks is a hundred and sixty concurrent operations against a machine sized for ten. Every resource gets a global budget, enforced centrally before work starts, not by each subsystem independently consuming until Postgres or memory gives out.

All of these are configuration rows, not constants. Three workload classes share the database with separate pools and budgets: interactive (the request path), background (tasks and agents), batch (ingestion, re-indexing, reporting). Six classes would be over-engineering at this size; one is what causes an ingestion run to make the chat slow.

Idempotency, and the problem this design did not previously answer

This was a genuine gap, and it matters most exactly where the system is most ambitious — browser writes and connector side effects. Retrying blindly repeats the action; not retrying loses it. The protocol's own recent revision removed message redelivery, so connector-side idempotency is mandatory rather than optional.

Every side-effecting operation carries an idempotency key and moves through explicit states: PENDING → SENT → UNKNOWN → VERIFYING → SUCCEEDED | FAILED. UNKNOWN is the important one, because it is the honest state after a crash, and it resolves by verification against the target system rather than by retry. Every connector must therefore implement a read-back that can answer "did operation X land?". A connector that cannot is restricted to read-only tools, and that restriction is declared in its manifest rather than discovered later.

One critical path, not one live fetch

The earlier constraint of "at most one live fetch per question" was too rigid — some questions genuinely need the CRM, the helpdesk and the ledger. The correct formulation is one critical path with parallel I/O: independent source calls fan out concurrently and the latency budget covers the slowest, not the sum. The per-source and global call budgets still apply, so parallelism cannot be used to evade the rate ceilings in §8. The dependency graph already built for multi-agent work is reused here for connector calls.

Per-connector rate limiting

A token bucket, circuit breaker and retry policy sit in front of every external system, owned by the connector layer rather than by callers. Twenty agent runs must not independently decide to call the same API twenty times. Per connector we track requests per second and minute, concurrency, 429 rate, latency and error rate — and the ceilings from §8 are configured here, not remembered.

Browser scheduling

Browser work is the most expensive subsystem, so it gets its own scheduler: global concurrency, memory and CPU limits, per-domain limits so one misbehaving automation cannot occupy every slot, per-agent limits, and a global kill switch.

Service levels, to be validated in stage 1

Every request records: request and trace id, principal, agent version, policy epoch, entitlement hash, lane, model, provider, time to first token, input and output tokens, tool count and latency, connector, cache hit or miss, redaction count, fallback count, retry count, final status. This is mandatory production telemetry, not optimisation instrumentation — the numbers above are provisional until stage 1 measures them, because the predecessor system's own figures did not reconcile.

Recovery objectives, stated per profile

"Backups work" tells a client nothing about resilience. These numbers do, they belong in the proposal, and backup frequency follows from them rather than the reverse. The single box remains the default and remains a large failure domain — the mitigation is that the two-box split is designed now and built when triggered: application and browser on one, database and object store on the other, with no application change required.

Failure-mode matrix and chaos testing

Before implementation goes far, the team produces a failure-mode matrix: for every component, what failure looks like, the user impact, the recovery path, and the data risk. Every operation is then classified as safe to retry, unsafe to retry, retry only after verification, or requires a human.

The tests that matter are not the happy paths. Kill Postgres, the model provider, a connector mid-call, the browser, the worker mid-task. Return malformed JSON and 429s. Fill the disk. Change a policy during an active task; disable a user during one. And the decisive one: kill the worker immediately after every side-effect boundary and verify the system recovers without repeating the action. That is how durable execution is proven rather than assumed.

26Build plan

Roughly seven months, usable at the end of every stage. Three sequencing rules worth defending in review:

• The gate is stage 1 even though it demos badly, because everything built before it has to be revisited after it.
• Templates are stage 2, because they make the second deployment fast and let someone other than the original developers create a working agent.
• Browser work splits across stages 5 and 6, along the 70%-read versus 46.6%-write line. Reading a client portal that exposes no API is useful and low-risk, so it ships with the runner in stage 5. Writing is held back for the envelope, enforcer and out-of-band verifier, because a wrongly-reported success corrupts a client's records while a failed read costs a retry. This also front-loads the expensive infrastructure — sandbox, egress proxy, credential leases — so stage 6 is shorter than it first looked.
• The execution kernel moves into stage 2, ahead of agents rather than arriving with the task lane in stage 5. Idempotency, durable checkpoints and admission control are not optimisations here; they are the reliability model that everything with a side effect depends on, and retrofitting them means revisiting every connector. The trade-off is honest: it adds roughly a week before anyone sees a template, and one independent review argued for a full stage of its own. Templates stay in stage 2 rather than slipping to stage 3 because they are what lets someone other than the original developers create a working agent, and that milestone protects the project.

27Open questions

1. Durable execution. Hatchet is the default; Temporal if scale demands it. The LangGraph re-drive driver is ours to build. Confirm before stage 5.
2. Not yet designed: multi-language retrieval including Chinese lexical search and Singapore NRIC/FIN recognisers; accessibility, particularly screen-reader-safe streaming; mobile and PWA; conversation export and eDiscovery; retention and DSAR mechanics; sensitive-topic interception for HR and grievance; API versioning policy.
3. Not measured: the lane split and output tokens per answer. Instrument in stage 1, size in stage 3.
4. Per client: whether their VPS exposes /dev/kvm, which decides what sandbox isolation can be promised.