Company OS Architecture Overview

Company OS Architecture Overview

Company OS is structured as a layered platform with distinct agent classes, foundational primitives, and irreversible architectural decisions (one-way doors). This overview synthesizes the core structure from ADR-0001.

Three Layers

The architecture consists of three concentric layers, from outer (user-facing) to inner (data and core applications):

Harness / Channel

The outermost layer encompasses communication channels where users interact: WhatsApp, Telegram, Slack, Teams, ChatGPT, and Claude Code. For tenants, the OS provides these channels directly; for platform operators (like Ryan), it integrates with external systems such as openclaw/grokbot. This layer handles user ingress and egress but contains no business logic or tenant data. ¹

Company OS (Control Plane)

The middle layer provides administrative and control functions. It bundles all MCP/REST connections, enforces role-based access control (RBAC) per role (e.g., recruiter vs. CFO), manages costs, observability, and evaluations, validates user actions, hosts the skills library, and uses LiteLLM for model routing and Langfuse for tracing. Every agent action passes through this layer. ²

Core Apps + Data

The innermost layer contains tenant applications and data stores: ATS, CRM, Linear, GitHub, Job Intelligence (the first application), hot/cold data storage, and a BI layer above. All actions and tool calls are written to this layer. ³

Two Agent Classes

Agents operating within the Company OS layer are divided into two classes, separated by their access to tenant data:

Ops Agents

Handle ongoing, operational tasks that require access to tenant data and systems: publishing job postings, sending invoices, processing meeting transcripts, and triaging email. These agents act as persistent automations within a tenant’s context. ⁴

Factory Agents

Focus on software creation tasks that do not touch tenant data: building pages, creating new agents, and establishing integrations (e.g., with Linear, GitHub, CI systems). Factory agents are restricted to capabilities targeting developer tooling and are explicitly denied access to tenant-app capabilities. ⁵

The separation ensures Factory agents cannot accidentally or maliciously access or modify tenant data, as enforced by capability registry permissions. ⁶

Five Primitives

Company OS provides five foundational primitives that compose all agent actions, applied in this order:

Principal

Represents an identity capable of acting within the system: a tenant, user, agent, or factory. Agents possess their own credentials and a designated human accountable principal. The Principal primitive includes an identity crosswalk that resolves channel-specific identifiers (e.g., WhatsApp number, Teams user ID, Better Auth session) to a single principal, preventing implicit principal creation. ⁷

Capability

Registered by applications, defines an invocable function with its input/output schema, permission requirements, effect class (e.g., read, write, delete), and reversibility. The Company OS is the sole invoker of capabilities; applications do not call them directly. ⁸

Task

Encapsulates an intention to perform work, comprising: actor (principal), goal, tenant context, and approval class. Tasks are routed deterministically for fixed agents (e.g., Ops agents) or via model-driven routing for others. The Task primitive is not a storage unit but a flow descriptor. ⁹

Receipt

Records every atomic action or tool call executed by the OS. Contains: correlation ID (linking to the initiating task), tenant ID, principal ID, capability invoked, effect class, target, costs (model and infrastructure in cents), token usage, Langfuse trace ID, outcome (pending, success, failed, denied, uncertain), and timestamps. Receipts form the immutable basis for billing and auditing; every action generates exactly one Receipt. ¹⁰

Policy

Encodes approval logic as data, specifying: applicable roles, effect classes, goals, limits, validity periods, and stop conditions. Policies are evaluated by the OS before action execution, replacing hardcoded approval checks. ¹¹

Channel ingress, admin UI, skills library, and BI systems consume these primitives but are not primitives themselves. ¹²

Four One-Way Doors

These architectural decisions are effectively irreversible after initial migration due to deep system integration. Acceptance requires explicit owner approval (Robbie) as noted in the ADR. ¹³

Tenant Isolation

Implements row-level security (RLS) in Postgres with a mandatory tenant_id column in all tables of the os schema and any app containing tenant data. A TenantContext Effect service scopes every database connection (SET LOCAL app.tenant_id). Queries lacking this context fail at compile time. This ensures app-level bugs cannot cause cross-tenant data leaks. ¹⁴

Principal Identity Across Channels

Unifies identities from WhatsApp, Teams, Better Auth, and other channels into a single principal record. The OS never implicitly creates principals; only tenant administrators may link channel identities to a principal. A WhatsApp number, Teams user ID, and auth session resolving to the same principal are treated as one entity; mismatches are rejected. ¹⁵

Metering Unit

Defines the capability-invoke as the billable event. Tool calls and model costs are recorded as child receipts (via parent_receipt_id) under the parent invoke receipt. The Receipt structure captures all cost dimensions: model costs (cents), infrastructure costs (cents), input/output tokens, and Langfuse tracing ID. Metering is a primitive, not a retrofit, enabling per-action billing from the first line of code. ¹⁶

Factory Principal Restrictions

Limits principals of class factory to capabilities with target: dev-tooling (e.g., Linear, GitHub, CI, deploy systems). The registry permission check rejects any attempt by a factory principal to invoke a capability with target: tenant-app (e.g., search_aanvragen), returning a denied outcome in the Receipt. This ensures factory agents cannot access tenant data or applications. ¹⁷

Related Concepts

• For layer details, see Architecture Layers
• For primitive definitions, see Primitives
• For one-way door specifics, see One-way Doors
• For request flow examples, see Request Flow