Architecture

AIOE is the server half of a boundary AI Workbench already has: workbenches send events, usage and audit records out, and take policy, a catalogue and remote-control requests in. This page explains the pieces, how data moves between them, and why it is built this way.

The pictureCopy Anchor Link

          DNS: aioe-discover.<your domain>  ->  CNAME or TXT  ->  API host
                                  |
AI Workbench (desktop) --HTTPS--> AIOE API <--HTTPS-- Console (browser), mobile app
   events, usage, audit  -> ingest      |   stateless, one or more replicas
   catalogue             <- catalogue   |   people: your identity provider's tokens
   policy                <- policy      |   workbenches: tokens AIOE issued
   registration          -> fleet       |
   remote control        <> relay       +-- PostgreSQL: everything kept
   overlay agent         <> mesh        +-- Redis: shared live state between replicas
                                        +-- Mesh relay and gateway (optional overlay)

The piecesCopy Anchor Link

The API is one stateless service. Every request names the guard that admits it: a workbench's or node's token, a person's sign-in, either, or an administrator's. It keeps everything in PostgreSQL, applies its own schema migrations when it starts, and uses Redis only to share live connections between replicas.

The console is a static web app. It reads the public discovery document to learn your identity provider, signs the person in, and calls the API with their token. It looks and works like AI Workbench itself.

The mobile app signs in the same way, and works with workbenches, approvals, agents and the inbox.

PostgreSQL holds your organisation: enrolled devices and their hashed tokens, policies, the catalogue, projects and boards, memory, sealed secrets, the overlay's nodes, and the streams workbenches report (events, usage, audit, task snapshots). The audit table accepts only new rows.

Redis carries remote-control requests between replicas, fans out live board and inbox updates, and remembers proof IDs for key-bound tokens. See Redis for more than one replica.

The mesh relay and gateway are optional. They carry the WireGuard overlay. See Overlay and relays.

How a workbench joinsCopy Anchor Link

1. Discovery. A person enters their work email in AI Workbench. The workbench looks up aioe-discover.<domain>, follows it to your API, and reads /.well-known/aioe.json: your organisation's name, the API and relay addresses, and your identity provider. See Publish the discovery record.
2. Enrolment. The workbench asks the API for a device code (the OAuth 2.0 device authorisation flow) and shows the person an eight-character code. The console opens with it.
3. Approval. The person, signed in to the console, approves the code. That binds the workbench to them and to your organisation.
4. Tokens. On its next poll, the workbench receives an access token and a refresh token that AIOE issued. One token serves everything the workbench does with AIOE.
5. Work. The workbench registers with the fleet and sends heartbeats, posts events, usage and audit to ingest, pulls the catalogue and the policy, and holds one stream open to the relay.

How remote control worksCopy Anchor Link

The workbench opens no inbound port. It keeps one Server-Sent Events stream open to the API. A person in the console or the mobile app sends a request for that workbench; the API writes it to the stream, and the workbench answers. The workbench itself checks the request against the scopes it was granted and its policy, carries it out with its own code, and records it in its audit trail under the real person. AIOE adds no second way of doing anything on a workbench.

With the overlay, the same request can travel to the workbench over WireGuard through the platform's gateway, signed so the workbench can tell it came from the platform. If that fails, it falls back to the relay.

PrinciplesCopy Anchor Link

The platform never edits a repository. It sends policy and requests; the workbench applies them on the machine, and stays fully usable offline.

One contract, versioned. Every message between a workbench and AIOE has a schema with a version, and both sides validate it.

Your organisation on every row. Everything AIOE stores is filed under an organisation, and the organisation always comes from a verified token or from the host name a request arrived at, never from what a request says about itself. See Tenancy and tokens.

Portable. No cloud provider's SDK inside the services. The same images run from Docker Compose, the Helm chart, or the Azure template.

Same look as the workbench. The console uses AI Workbench's design, so a person moving between them finds the same names, icons and layout.

Deployment shapesCopy Anchor Link