Timebase Atlas Architecture

Overview#

Timebase Atlas ships as one container running one process. That single process serves the browser interface, the REST API, three SignalR hubs, an MCP endpoint and an i3X read surface, and it also is the runtime: it stores your model in Git, compiles it, holds the compiled result in memory, executes Cypher queries against it, receives live values from connectors and streams them out again.

Two external Timebase components attach to it over the network, and both connect outward to Atlas, never the reverse:

• Connector brings data in.
• Bridge takes data out.

One platform component is a prerequisite rather than an attachment: Pulse, the Timebase identity provider. Atlas ships with authentication on, and it is also the only route to the AI assistant's models.

This article describes what actually runs, which surfaces exist, where your model is stored, how a value travels from a data source to a downstream system, and the limits of the current design. It is written for someone planning, deploying or diagnosing an Atlas installation.

The one thing to take away: Atlas is a single-instance, single-process system today. There is no separate runtime service to install, no cache tier, no message bus, and no supported way to run two Atlas instances against one data volume.

The shape of a deployment#

Picture four boxes and three arrows.

In the middle is one box: the Atlas container, listening on 4551 (HTTP) and 4552 (HTTPS). Inside it, and not separable from it, are the browser UI, the API, the Git-backed store of your models, the compiler, the in-memory compiled worlds, the Cypher query engine and the live-value machinery.

Around it:

• Connectors (one or more, on any host) hold an outbound SignalR connection into /hubs/connector and push rows of data up.
• Bridge (optional, one or more) holds outbound SignalR connections into the value hub, one per (branch, domain) world, and writes what it receives to SQL, MQTT, Kafka, Event Hubs, Snowflake, HTTP and so on.
• Pulse issues the bearer tokens that every Atlas surface checks, and proxies the AI assistant's model traffic.

There is no fifth box. Nothing sits between the connector and Atlas, and nothing sits between Atlas and Bridge.

Ports#

The ports come from Kestrel:Endpoints in settings.config, not from ASPNETCORE_URLS, which controls nothing in Atlas.

What Atlas ships as#

Atlas deploys as one process, Atlas, with two supporting libraries that other Timebase components reference.

What runs inside Atlas#

These are the subsystems of that one process.

Two more pieces sit behind the value hub: the live-value fan-out, and a background service that maps property-change events onto value-hub subscription keys.

The eight top-level surfaces#

Atlas maps eight top-level route families. The first is the general-purpose integration surface.

The three hubs all ride MessagePack, not JSON. A browser client must add @microsoft/signalr-protocol-msgpack; the default JSON protocol cannot discriminate the Column union and you get untyped property bags.

Anything that matches none of these is answered by app.MapFallbackToFile("index.html"), so a wrong path returns the SPA shell as 200 text/html rather than 404.

How Atlas stores your model#

Atlas keeps your domains and libraries in a Git repository on the data volume. Branches are versions, every write is a commit, and the container therefore has a real git dependency: the image installs git and sets git config --global --add safe.directory '*' so it can operate on a mounted volume.

The read and write paths are asymmetric.

Reads are worktree-free and SHA-pinned. A read resolves the branch to a commit SHA once, lock-free, then reads file contents straight out of the Git object database at that commit. No branch is created, no worktree is checked out, and neither the per-repository lock nor the per-branch lock is taken. Any number of reads run in parallel, and they run alongside writers, because a pinned-SHA read is unaffected by the branch tip moving.

Writes take a worktree and a lock. A write creates a transient worktree, commits into it, advances the branch, resyncs the root working tree, and removes the worktree. Writes to the same branch are serialised per branch, and every write additionally takes a per-repository lock. Because one server serves one repository, that lock serialises the write path across the process.

Two boot-time behaviours are worth knowing about:

• Garbage collection is pinned off. Every boot sets gc.auto=0 and core.autocrlf=false, so that background repacking cannot run under a live read. Loose objects accumulate, so plan for steady growth on the data volume and pack the repository against a stopped instance.
• The system library is kept current. Atlas compares its own copy of atlas-core against yours at every start, copies it in if it is missing, and restores the shipped version if they differ. This is how a framework vocabulary upgrade reaches your model with a new image.

Inside the Config directory but outside Git history are compiled-worlds.json, draft-sessions.json, /agents/, /skills/, /views/ and /.worktrees/; the assistant's chat state lives in the Data directory. A clone or bundle of the repository therefore leaves behind your agent and skill definitions, saved views, the compiled-world records that drive restart recompilation, and every author's unpublished draft session, and does not carry the Data directory. Back up the whole Atlas directory or volume.

Draft sessions also cost disk: each one is a real checked-out worktree at {root}/.worktrees/.v2-draft/{hash}, one per (identity, target branch).

Compiling, and the World#

A domain is authored, then compiled. Compiling is PUT /api/v1/branches/{branch}/domains/{domain}/world. It validates the whole domain before it builds, so while any error-severity violation is outstanding it returns 422 with a violations[] array, and the World is built once the last one is cleared.

On success it produces a World: every type, every expanded instance, every relationship, in memory. Worlds are cached per branch and domain. Each entry holds the World itself, a query engine with its own persistent query cache, the compiled function registry, and the compiled functions for that model.

Three consequences that matter operationally:

• Recompiling replaces the cached World in one step. Queries in flight finish against the previous World, and the new one answers everything after the swap.
• A cached World stays resident for the life of the process. An entry is replaced by a newer compile of the same branch and domain.
• Memory scales with branches multiplied by domains, not with domains. Because a branch is a version in Atlas, compiling the same domain on ten branches holds ten complete Worlds at once. This is the figure to size against.

Restart behaviour#

Atlas recompiles at boot. A background service loads every recorded (branch, domain) pair from compiled-worlds.json and recompiles them sequentially, one at a time, while Atlas is already bound and serving traffic. Domains become queryable one by one as each recompile lands.

So restart time to full availability grows roughly linearly with the number of compiled (branch, domain) pairs, and a query against a domain whose turn has not come yet reports the domain as not compiled. A handful of domains clear in seconds; a large estate takes longer. No manual recompile is needed either way.

One class of domain compiles later: a domain whose instances come from a connector-driven source has its declared binding paths captured at boot, and it is compiled the moment a connector advertises paths that resolve them.

The knob is Compilation:AutoRecompileOnStartup, default true.

The runtime data path#

Ingress: from a data source to the compiled World#

The whole path is in one process. There is no hop out of it at any point.

1. A connector connects outward to /hubs/connector and calls Handshake(ConnectorAdvertisement), advertising the concrete binding paths it can serve. Atlas answers with a HandshakeResponse carrying the AtlasSessionId, so the connector can detect an Atlas restart.
2. Atlas resolves the binding paths declared in your instance maps against the in-memory connector registry and asks the connector to Subscribe to the ones it needs. GetRange, Subscribe and Unsubscribe are handlers on the connector that Atlas invokes.
3. The connector pushes unprompted as data arrives: PushSubscriptionRows(subscriptionId, CompoundRowSet, EmitKind, asOfT), plus PushSubscriptionStatus and PushSubscriptionWatermark.
4. Atlas writes the rows into the compiled World's columnar store and publishes a change on the in-process property change bus.
5. The calculated-property and reference-property reactors pick that change off the bus and recompute dependent properties.
6. The change is mapped onto value-hub subscription keys and streamed to whoever is subscribed.

Egress: Bridge#

Bridge is the counterpart to Connector, and its connection is one hop, not three.

Bridge opens a SignalR connection directly to the value hub at /hubs/v1/branches/{branch}/domains/{domain}/subscribe, one connection per world, using the shared value hub client library. There is no routing layer between them and nothing in Atlas dispatches to Bridge.

Each Subscribe… method on the hub is a server-to-client stream of ValueRowSetDto over MessagePack. Cancelling the stream is the unsubscribe; there is no separate call. Streams do not auto-restore after a reconnect, so a client must re-establish them. A fifth method, SubscribeToTypeDescription, streams a type's compiled shape (its columns, endpoints or enum roster) rather than values. See Atlas API - Subscribing to Live Values.

A Bridge value subscription declares one of exactly four shapes:

A Bridge Type description subscription (TypeDescription) is a fifth kind that follows SubscribeToTypeDescription instead of a value stream. It is chosen when the subscription is added and carries a type and no instance. See Exporting Data with Bridge.

Transformation and delivery are the job of a per-destination plugin over a shared rowset decoder: Microsoft.SqlServer, PGDG.PostgreSql, Oracle.MySql, IETF.Http, MQTT, Apache.Kafka, Microsoft.EventHubs and Snowflake.SnowpipeStreaming. A single Bridge instance can feed several sinks at once.

Queries#

A query is parsed and executed in process, against the cached compiled World for that branch and domain. Nothing is routed elsewhere, so there is no query placement to tune.

Querying a domain that has never been compiled returns 400 with "code": "Query.NotCompiled".

Point normalization#

When several inputs arrive at different times and rates, Atlas can align them onto a common instant before a calculation runs. This is a host-level setting, not a per-domain one: LiveProjection:AllowedLatencyMs, default 2000. It also requires opting in on the data type (a time-axis field) and on the function (contributing inputs). It applies to calculations and to live full-instance and full-type subscriptions.

Pulse is a prerequisite, in three separate ways#

The shipped settings.config contains:

"Pulse": {
  "Host": "localhost",
  "Port": 4542,
  "UseTls": true,
  "Auth": {
    "Enabled": true,
    "ClientId": "Atlas",
    "ClientSecret": ""
  }
}

1. Authentication is on by default. Every /api/v1 route, all three hubs, /mcp and /i3x/v1 require a credential. A caller's Pulse token must list Atlas (the value of Pulse:Auth:ClientId) as an audience.
2. The browser interface redirects to Pulse. The page shell loads anonymously, resolves the signed-in identity, and redirects to the sign-in flow when there is none.
3. The AI assistant reaches its model through Pulse. Agent models are Pulse-proxied Gage, discovered from Pulse's own catalogue and configured as Pulse:Gage {Enabled, Agents, Guardrails, Dictation, Resilience}. ANTHROPIC_API_KEY is forwarded by docker-compose.yml and is not read by Atlas.

You can set Pulse:Auth:Enabled to false for a local evaluation. Writes are then attributed to Anonymous, so use it to look around rather than as a deployment posture.

Licensing is separate. /app/license projects the verified effective licence to the interface for display.

How Atlas scales today#

Important: Atlas runs as a single instance. Run one Atlas process per data volume and scale it by giving that machine more memory and CPU.

Six pieces of state are held per process, which is what makes this the supported shape:

• Hub subscriptions are per process. SignalR runs without a backplane, so a subscription held on one instance is not visible to another.
• The connector registry is per process. It is held in memory and keyed by live connection, so connectors attached to one process are known only to that process.
• The world cache is per process. Compiled Worlds live in the same process that compiled them. Compiling on instance A leaves instance B still reporting the domain as uncompiled.
• The Atlas session id is per process. One identifier is minted per process and stamped on every handshake, so a connector can detect an Atlas restart.
• The write locks are process-local. The per-branch write lock and the per-repository Git lock are both held in the process, which is what serialises writes to one repository.
• One server, one repository. The configured data root is authoritative, and one server serves exactly one repository.

What is true about growth:

• Reads scale with CPU and do not contend, because the read path is lock-free and SHA-pinned.
• Writes to the same branch are strictly serial, and all Git-mutating work in the process serializes behind the single repository lock. Authors on different branches avoid the branch lock but still meet the repository lock.
• Memory is dominated by the cached Worlds, one per branch and domain, resident for the life of the process.
• Splitting a very large model means splitting it into separate domains. A single domain compiles into one in-memory World and cannot be divided.

Sizing#

Four things drive Atlas's memory footprint:

• the number of (branch, domain) pairs compiled at once,
• the entity and edge count of each World,
• the compiled function assemblies each World holds,
• the number of live value-hub subscriptions.

For starting figures and the planning rule, see Hardware Requirements Guide.

Deployment topology#

The shipped docker-compose.yml declares exactly one service:

services:
  atlas:
    image: timebase/atlas:${TIMEBASE_TAG:-latest}
    hostname: atlas
    ports:
      - "4551:4551"
      - "4552:4552"
    volumes:
      - atlas:/atlas
    environment:
      - Certificates=/atlas/certificates
      - Settings=/atlas/settings
      - Config=/atlas/config
      - Data=/atlas/data
      - Logs=/atlas/logs
    restart: unless-stopped

One service, one volume. In the platform Compose file Atlas, Pulse, Connect and Bridge share one project and one network, so each reaches the others by service name - pulse, atlas - and nothing has to be started in a particular order beyond what the file's depends_on entries express.

Configuration precedence#

The configuration sources are layered in this order:

appsettings.json -> appsettings.{Environment}.json -> settings.config -> environment variables -> command line.

Because settings.config is added before the environment-variable source, the environment and the command line take precedence over the file for every key - Pulse:*, Kestrel:* and Serilog:* included. A value in the file holds only where nothing outranks it.

settings.Docker.config is not a file in the volume and not a layer that is loaded. It is an overlay embedded in the image, applied once: the first time Atlas starts into an empty volume it composes settings.config from its template patched with that overlay, which sets Pulse:Host to pulse, and never reads it again. Change the address in settings.config, or set Pulse__Host as an environment variable, which outranks the file.

Atlas reaches its language model through Pulse Gage, so no API key is configured on Atlas itself.

Troubleshooting#

Related articles#