Architecture

Runtime flows

The C4 diagrams show structure. These three views show behaviour — what actually happens over time, and which service is waiting on which.

01

Publishing a version

Four participants. The worker does the heavy lifting and never holds state.

Dynamic view 01 — publishing a version, seven steps across four participants
Swimlane diagram of the APIHUB publish flow across the UI, backend, build consumer and linter
UI / CI Backend Build Consumer Linter
  1. 1

    Upload sources

    Multipart or ZIP

    UI / CI
  2. 2

    Create build task

    Stored in PostgreSQL

    Backend
  3. 3

    Poll and receive

    Task ZIP with configuration

    Build Consumer
  4. 4

    Parse · normalize · diff

    api-processor pipeline

    Build Consumer
  5. 5

    Store results

    Documents, operations, changes

    Backend
  6. 6

    Publish event

    Olric topic

    Backend
  7. 7

    Lint and score

    Spectral, optionally AI

    Linter

Steps 3 and 4 repeat for every document in the package. Step 7 happens asynchronously, so publishing never waits for linting.

02

Finding APIs already running

The only flow that starts outside APIHUB — in someone else’s cluster.

Dynamic view 02 — discovery starts with the agent registering itself
Swimlane diagram of the APIHUB discovery flow across the Agents SPA, agents backend, agent and cluster services
User / Agents SPA Agents Backend Agent Cluster services
  1. 1

    Register

    On startup, then heartbeat

    Agent
  2. 2

    Run discovery

    Pick a namespace and workspace

    User / Agents SPA
  3. 3

    Forward request

    To the chosen agent

    Agents Backend
  4. 4

    List services

    Via the Kubernetes API

    Cluster services
  5. 5

    Probe endpoints

    Six runners in parallel

    Cluster services
  6. 6

    Return findings

    Documents and failed calls

    Agents Backend
  7. 7

    Promote snapshot

    Publish versions to the Portal

    Agents Backend

Nothing is published automatically: discovery produces a snapshot, and a person decides whether it becomes a catalogue version.

03

How an AI agent reads the catalogue

Two paths lead into the same tools: an external client speaking the Model Context Protocol, or the chat built into the Portal. Access control is applied per user on every call, on both paths.

Dynamic view 03 — two doors, one room
Two paths into the APIHUB catalogue tools: an external MCP client and the built-in Portal chat, both converging on the same four tools

Path A · external MCP client

  1. 1

    Client initialises

    Cursor, Claude or a bot authenticates with an API key or personal token

  2. 2

    Session opens

    Streamable HTTP transport, idle timeout 15 minutes

  3. 3

    Tool call

    search, specification, diff or document

  4. 4

    Backend answers

    Access control applied per user before anything is returned

Path B · the built-in chat

  1. 1

    Question arrives

    Streamed over server-sent events from the Portal

  2. 2

    Model plans

    The same catalogue tools plus a clarification tool

  3. 3

    Loop runs

    Up to ten tool calls per turn, each one access-checked

  4. 4

    Answer streams back

    Generated files offered as temporary downloads

Shared catalogue tools

search_api_operations get_api_operation_specification get_api_operation_diff get_document

The linter exposes a further MCP endpoint of its own — list_linter_issues_for_package_version — so an agent can ask what is wrong with a version and receive the issue list directly, without going through the catalogue tools at all.