Skip to content
Describes how WilsonOS is designed to work.What works today →

Architecture

This is the whole system on one page, for anyone joining the build: how WilsonOS is wired today, how it should be wired in about ninety days, and an honest reading of how far each part has got. The one thing to hold onto is that WilsonOS is a thin control plane over a replaceable engine. It owns the brands, the records, the review path, the memory and the guardrails, and it treats the model runtime as something you could swap without any of that changing. Almost every choice below follows from that.

The target is mostly consolidation, not invention. Almost every box on the target board already exists in part; the work is making the strongest existing pattern the only one.

  1. One core instead of three write paths. Each kind of record has one sanctioned writer, but today that rule is kept separately by the app, the provider door and the writer tools. In the target the app’s service layer is the only thing that writes, and every tool, agent and screen asks it.
  2. The agent sandbox becomes the rule for everyone. A conversation runtime already has the strongest boundary in the system: its own account on the server, a read-only view of the files, a scoped pass and no keys. Scheduled runs and terminal tools move inside the same boundary.
  3. Documents join media in one object store. Documents get ids and versions the way images already do, so a version number always means the same bytes. Accepted as a decision; not yet built.
  4. The outside world can wake an agent. Today only you or a schedule starts work. An event door lets a customer reply, a spend alert or a form fill land as a recorded event routed to the right agent or engine.
  5. Engines become one service with one cockpit template, so turning on a new channel gives you its screens.
  6. The brain moves from “you and one agent” to “the brand”, with every entry stamped with who added it.
Who starts workfour ways in · each lane runs straight down to the door it uses
You, in a browser
desktop or phone · the chat panel is on every screen
The outside world
replies, alerts and form fills cannot reach an agent yet
(agents start work too: they live one level down, inside the harness)
A schedule
each agent keeps a registry of scheduled runs
Builders and coding agents
people and coding agents working in the repository
On the server, outside the appthe agent harness · one bridge per agent, one runtime per conversation
(the browser is the client)
(nothing listens for outside events)
Agent bridge
always on, one per agent
starts a runtime per conversation, loads what the agent should know at the start, streams the reply back
Conversation runtime
the model, working
its own account on the server · a read-only view of the code and brand files · a short-lived, brand-scoped token · never a provider key
Scheduled runnergap
runs an agent on its schedule
today it runs outside the per-conversation sandbox
Terminal session
a builder or coding agent
works in the repository with operator access
Writer toolsgap
one sanctioned writer for each kind of record: tasks, versions, media, memory, skill runs, measurements
from a runtime they go through the app · from a schedule or a terminal they still write to the database directly
Trust boundary · people sign in · agents carry a short-lived, brand-scoped token and never a provider key
Inside the appfour doors, each with its own check, and a missing fifth
Web app
every screen, and the routes behind them
Checks: a signed-in session
Event doorgap
missing · outside events have nowhere to land
Runtime API
what agent runtimes and their tools call: tasks, versions, media, memory, files, and the provider gateway
Checks: the runtime token
Internal API
bridges, schedules and workers on the same server
Checks: a server-only credential
Corewhere the business logic lives · today three paths, not one layer
Domain logic: no single service layer yetgap
App modules
the web app writes some records itself
Provider gateway
holds every key, writes a receipt for every paid call
Writer tools
called by the app, by runtimes, and directly by schedules
Stores and providersrecord chips are coloured by the pillar that owns them
Database
about 140 tables · exactly one writer for each
conversationsmessagesruntime tokensrunsgoalstaskstask versionsreviewsassetspublicationsskillsflowsskill runsshowdownsconnectionsmemory entriesbrand docsideaselementsdesign systemsmetric snapshotsinterventionsreflectionspatternsad recordspin recordsusersworkspacesbrand accessoperations health
Object store
media, addressed by content
a primary copy and an off-site backup
Repositorygap
brand kits, skills, flows
documents still live here today
Models and services
the model, image and video generation, ads, pins, analytics, mail
reached only through the gateway
A labelled diagram, not a screenshot. Record chips are coloured by pillar: charcoal agents, gold goals, tasks and artifacts, teal capabilities, plum the shared brain, indigo engines, grey the foundations.

Read it top to bottom. The top row is everyone and everything that can start work. The second band is the agent harness: the always-on bridge for each agent, the runtime that does the work in one conversation, the scheduled runner, and the writer tools. Below the trust boundary are the app’s doors, each with the check it performs, then the core where the logic lives, then the stores and the outside services. A dashed box is missing today; a dashed arrow is an alternate or partial path. A red tag marks a gap the target closes, a green tag is new in the target, and an amber tag is a direction leaning-decided rather than signed. The two boards share one grid, so switching between them shows exactly which boxes change. The target shows direction, not availability; what you can use today is in What works today.

Four design choices carry the weight:

  • Work always enters the same way. A message, a schedule and a signal are three doors onto one recorded path, with the same scope rules. See Agents.
  • The runtime is a boundary, not a process detail. Each conversation gets its own working area and short-lived pass, so two conversations with the same agent run at once and neither can read the other. See how an agent runs.
  • Nothing reaches the outside world directly. Generation, publishing, memory and provider reads each go through one door that holds the real credential and writes the receipt. A runtime that wanted to skip the door could not: it never had the key. See Capabilities.
  • The loop closes. What a run produced is reviewed, the rating is learned from, and what is learned changes what the next piece of work loads. See the eight stations, each with the files and tables behind it.

Each Today cell ends with its evidence type, the same vocabulary What works today uses, so every reading says what kind of check stands behind it. This is a reading of the architecture’s own contracts, not an availability table and not a roadmap with dates.

Subsystem Today Target What closes the gap
Triggers Built Three doors — message, schedule, signal — onto one recorded path. Runtime check Unchanged —
Agent runtime Acceptance in progress One isolated runtime per conversation, with its own working area and pass. Reported deployment The same, with recovery for work in flight stated and tested Live acceptance of the isolation boundary, and a stated recovery contract
Model engine One engine behind it The boundary is drawn so the engine is replaceable; one is wired. Written design A second engine on the same contract, proving the boundary An adapter at the runtime boundary, and assembling the start-up bundle explicitly
Capability catalogue Built Skills and workflows catalogued, discoverable, credited to the runs that used them. Runtime check Unchanged —
Doors Built Generation, media, memory and providers each have one door holding the credential. Runtime acceptance Unchanged —
Brand boundary Recorded, not refused Every call through a door records its brand. Instruction audit A call for the wrong brand is rejected Enforcement at the door, not only on the record
Artifacts Built, known defects The registry identifies records; versions are appended through one writer. Runtime check Registry-owned identity throughout A decided design, waiting on one upstream feed
Review Being rewritten Versions are reviewable and rateable. Runtime check One consolidated review surface The surface rewrite already scoped as its own work
Learn Input thin Ratings feed skill scoring. Runtime check Enough rated reviews for scores to mean something Rating reviews habitually — a practice gap, not a code gap
Measure Middle missing Sources land with provenance; some derived numbers are computed inside the screens that show them. Written design A named layer where derived metrics live as records Building that middle layer as a store
Identity & access Partly built Records carry their workspace and creator. Written design Access rules audited end to end, multi-customer An audit of the access policies, not new schema
Data governance Contract unsigned One canon, one writer is enforced in the tooling. Instruction audit The same, with the policy signed off Sign-off on the draft policy
Write paths Three paths The one-writer rule is kept separately by the app, the provider door and the writer tools, some of which reach the database directly. Instruction audit One service layer every door calls Consolidating the writers behind the app; tools become thin clients
Scheduled runs Outside the sandbox A scheduled run executes outside the per-conversation boundary. Instruction audit Every scheduled run in its own isolated runtime Handing scheduled runs to the conversation runtime path
Document storage Decided, not built Media is in the object store; documents still live in the repository. Instruction audit Media and documents in one store, by id Moving documents onto the registry media already uses
Outside events No door Only you or a schedule can start work. Instruction audit An event door, recorded and routed An events record and one inbound route
Engine service Built twice Predict, act, measure and learn exist separately in each built engine; neither closes its learn step. Instruction audit One engine service, three types, one cockpit template The engine contract built once, with today’s engines as its first two types
Shared brain Person-scoped Memory is scoped to one person and one agent. Runtime check Brand-scoped memory, stamped with who added it A brand scope on memory reads and writes
Ingestion One exception Most sources run through the shared adapter interface. Runtime check Every source through it Moving the advertising ingest onto the shared pattern

The specific gaps. Two record clusters have tables with no writer — one is read to avoid re-proposing something already rejected but nothing inserts into it, the other has live schema for a computation never built — and both need a decision, not a guess. One cluster has two writers with no documented split, which may be a deliberate stage-then-apply lifecycle or an accidental second writer. The derived-metrics layer is a contract, not yet a store. The target design is proposed, not signed, which is why parts of the target column carry written design. And the replaceable engine is unproven: a boundary that has only ever had one thing behind it is a claim, not a property.

More than a hundred tables group into thirteen clusters and six areas. Every record carries the workspace and brand it belongs to, which is what makes access rules enforceable rather than advisory.

Cluster Area Pillar What it holds Maturity
Identity and tenancy Identity & access Foundations Workspaces, brands, people, and the grants connecting them Done
Tasks and versions Work & artifacts 02 Goals, tasks, artifacts A unit of work, its versions, reviews and ratings Done
Conversations Work & artifacts 01 Agents Threads, messages, attachments, who is in a room Done
Content loop Work & artifacts 05 Engines (goals: 02) Goals, signals, ideas, hooks, scripts, productions, posts, performance Daily use
Media registry Work & artifacts 02 Goals, tasks, artifacts The identity of every generated or imported file, its bytes, labels and publications Done
Canon indexes Work & artifacts 03 · 04 Searchable indexes of skills, workflows, agents, wiki pages and distilled memory Daily use
Integrations Connected data & channels 03 Capabilities Per-account connections and what each service reported Daily use
Advertising and royalties Connected data & channels 05 Engines Campaigns, keywords, bids, spend, royalty reports, the decisions taken Daily use
Channel learning Connected data & channels 05 Engines What a channel engine tried, what happened, what it concluded MVP
Platform build Platform build & health not yet homed The system’s own projects, features and work packages MVP
Platform health Platform build & health Foundations Resource samples, process events, errors the app threw Daily use
Studio and configuration Studio & configuration 02 · 04 Folders, scratchpads, saved views, dashboards, design choices Daily use
External surfaces External surfaces outside the pillars Records belonging to a public-facing app MVP

Maturity uses the system’s own ladder — Done, Daily use, MVP, Proposed — and describes the cluster’s records, not the features built on them. Every cluster obeys one canon, one writer: each kind of data has exactly one place it lives authoritatively and one path that writes it, an agent and a person reach that same writer through a tool and an app action respectively, and a hand-edited record is treated as corruption, not a shortcut. The page names no tables or columns on purpose: they are the most changeable thing in the system, and developers read the generated inventory that ships with the code.

  • A document is not evidence. A claim moves up on a check in the running system or a dated acceptance, never on a merged change or a written intent.
  • No data is not zero. A surface with nothing behind it says not wired yet, and an incomplete calculation never carries a complete name.
  • The newest dated evidence wins. Where a contract, a status table and a page disagree, the most recently verified one is right. Several gaps above were found exactly that way.

Sources: docs/architecture/overview.md (incl. §Contract status), docs/architecture/views/system-map.html, docs/architecture/concept-map.json, docs/architecture/data-model.md (inventory by group; §Findings — no confirmed writer), docs/architecture/data-governance.md (canon policy, writer paths), docs/architecture/target-design.md (PROPOSED 2026-09-20), docs/architecture/engine.md; docs/architecture/measure.md §5, docs/wilsonos-app/capabilities.md (the maturity ladder), docs/DECISIONS.md (ADR-018, ADR-026, ADR-028) · Last verified 2026-10-06