> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matrices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

Matrices follows the following system

## What owns what

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
Workspace
├── Identities        Roles        Toolsets        Connections
├── Profiles          models[] · systemPrompt · hooks[] · roleIds[]
└── Agents            profileId · identity · budget?
    ├── Threads → Turns → Events / Waits
    ├── Memory (agent namespace)     + workspace-namespace memory
    ├── Schedules · Subscriptions
    └── Artifacts / Sites / Images
```

Everything above the agents line is *configuration* you write once and share:
[identities](/model/identities), [roles](/model/roles),
[toolsets](/model/toolsets), [connections](/model/connections), and the
[profiles](/model/profiles) (with their [hooks](/model/hooks)) that assemble
those into behavior. Everything below it is *what happened*: an
[agent](/model/agents)'s [threads](/model/threads),
[memory](/model/memory), and [schedules](/model/schedules), which are durable
and only reachable through that agent. [Feeds](/model/feeds) are the
exception. They're shared, and that's what lets agents talk to each other. All
of it lives in one [workspace](/model/workspaces).

## Cardinality

| Relationship | Shape | Notes |
| - | - | - |
| agent → profile | N:1 | many agents can share one profile |
| agent → identity | N:1 | set at creation, immutable |
| profile → roles | N:M | at most 8 roles per profile |
| role → tools | 1:N | allow and deny entries, 32 each |
| connection → owner | N:1 | owner is the `workspace` or one `identity` |
| thread → agent | N:1 | threads never cross agents |
| schedule → agent | N:1 | fires into a new or existing thread |
| subscription → (agent, feed) | N:1 each | one agent woken by one feed |
| feed → workspace | N:1 | feeds are shared, not agent-owned |

## What a turn freezes

When a turn starts, Matrices works out its configuration once and freezes it for
that turn and any replay:

* the profile ID and **profile version**
* the one **model** picked from the profile's selectors
* the **system prompt** and the **hook** list
* the **resolved access**, meaning what it may call: each selected role by
  version, the exact built-in tools, the eligible toolsets, and any
  conditional grants

Edit a profile, its `roleIds`, or a role's own rules and the change lands on the
next admitted turn. Work already running keeps the snapshot it started with.
The budget is checked at the same moment, so lowering one stops new turns rather
than killing a running one.

From there it loops: ask the model, run the tool calls the snapshot allows,
append the results, ask again. That same resolved access decides what the model
can find, and checks every call as it runs. Credentials are attached to the
outgoing request, so the model never sees a raw secret and never grants itself
anything.

## Control plane, data plane

```text theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
                     your app / the API
                            │
              ┌─────────────┴──────────────┐
              ▼                             ▼
      Control plane                    Data plane
  workspace · profiles · agents · roles  threads · turns · messages
  toolsets · model catalog               tools · waits · event logs
              │                             │
              │  signed turn snapshot       │
              └────────────┐   ┌────────────┘
                           ▼   ▼
                  model gateway · action gateway
                  memory · artifacts · scheduler
```

The **control plane** is configuration: what an agent is and what it may do.
The **data plane** is execution: what it actually did. One
[API key](/api-reference/overview#authentication-and-base-url) reaches both, and the
[API reference](/api-reference/overview) shows how the endpoints split.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.