Components¶

This section covers the eight independent GitHub repositories that make up the running platform and its deploy/observability tooling. Each ships its own Helm chart (or deploy mechanism), CI pipeline, and independent release lifecycle. There is no umbrella helmfile and no monorepo. Components compose into the platform at runtime but version, build, and deploy in isolation.

Two further repos support the platform without being runtime components and are documented outside this section: tatara-agent-skills (the source of the wrapper agent skills) and tatara-documentation (this site).

Component table¶

Plane model¶

The eight components fall into three functional layers.

Control plane¶

The control plane holds the decisions and the desired-state declarations. Nothing in the data plane runs without the control plane authorizing it.

Data plane¶

The data plane does the work: storing knowledge, executing agent sessions, and keeping the knowledge graph current.

Supporting infrastructure¶

Supporting components provide CI/CD, inter-agent coordination, and observability. They do not participate in the core agent turn loop.

Per-component summaries¶

How they compose at runtime¶

At runtime the components form two concurrent flows: the agent execution loop and the CI/CD supply chain.

Agent execution loop¶

A developer (or the operator's periodic brainstorm scan) labels a GitHub or GitLab issue. The operator picks it up and drives the following sequence:

sequenceDiagram
    actor SCM as GitHub / GitLab
    participant Op as tatara-operator
    participant Mem as tatara-memory
    participant Ing as repo-ingester Job
    participant Wrap as claude-code-wrapper Pod
    participant Cli as tatara-cli (MCP stdio)
    participant Chat as tatara-chat

    SCM->>Op: HMAC-verified webhook (issue labelled / push)
    Op->>Mem: provision memory stack (if new Project)
    Op->>Ing: spawn ingest Job for changed repo
    Ing->>Mem: POST entities + edges (code graph, semantic chunks)
    Op->>Wrap: spawn agent Pod (Task context injected as env)
    Note over Wrap: clone repo, configure MCP,<br/>optionally restore S3 conversation
    loop each turn
        Op->>Wrap: POST /v1/messages (turn prompt)
        Wrap->>Cli: MCP tool calls (memory query, subtask management)
        Cli->>Mem: REST (query memories, entities, code graph)
        Cli->>Op: REST (create / update Subtask, report issue)
        Wrap->>Chat: mid-session coordination messages (optional)
        Wrap-->>Op: callback POST (turn result, conversation pointer)
    end
    Op->>SCM: PR opened + issue comment (one PR per changed repo)

CI/CD supply chain¶

Component images and charts move from source repo to the cluster through the CI/CD supply chain, never by hand. tatara-argo-workflows was decommissioned (2026-07-05); it was homelab GitLab CI, never part of the tatara platform runtime. The in-cluster argo-workflows Helm release remains as separate, unrelated homelab infrastructure.

graph LR
    subgraph "Component repos"
        R1[tatara-operator]
        R2[tatara-memory]
        R3[tatara-cli]
        R4[tatara-claude-code-wrapper]
    end

    subgraph "Component repo CI"
        CI[build + test + lint\nimage + chart publish]
    end

    subgraph "Artifact registry"
        H[Harbor OCI\nimages + charts]
    end

    subgraph "GitOps deploy"
        HF[tatara-helmfile PR\nimage tag + chart version bump]
        ARC[in-cluster ARC runner\nhelmfile apply]
        K8s[Kubernetes cluster]
    end

    R1 & R2 & R3 & R4 -->|push / tag event| CI
    CI -->|docker push + helm push| H
    H -->|version pin bump PR| HF
    HF -->|merge to main| ARC
    ARC -->|helmfile apply| K8s

Component interaction map¶

The diagram below shows the full platform topology grouped by plane, matching the control / data / supporting classification above:

graph TB
    subgraph CP["Control plane"]
        Op[tatara-operator\nCRDs + reconcilers]
        HF[tatara-helmfile\nGitOps releases]
    end

    subgraph DP["Data plane"]
        Mem[tatara-memory\nLightRAG + Neo4j + Postgres]
        Cli[tatara-cli\nMCP stdio server]
        Wrap[tatara-claude-code-wrapper\nephemeral Pod per Task]
        Ing[tatara-memory-repo-ingester\nephemeral Job per ingest]
    end

    subgraph Sup["Supporting"]
        Obs[tatara-observability\nGrafana alerts via Terraform]
        Chat[tatara-chat\nagent chat rooms]
    end

    HF -->|helm apply| Op
    HF -->|helm apply| Mem
    HF -->|helm apply| Chat
    Op -->|spawns| Wrap
    Op -->|spawns| Ing
    Op -->|provisions per-project| Mem
    Wrap -.-|MCP stdio| Cli
    Cli -->|REST| Mem
    Cli -->|REST| Op
    Wrap -->|REST| Chat
    Ing -->|REST| Mem
    Obs -->|Grafana alert webhook| Op

Release model¶

Since the semver push-CD migration (2026-07-05), every component that ships a container image publishes at a bare-semver image tag (vX.Y.Z) and its chart at the matching bare semver (X.Y.Z). The release pipeline cuts the tag from a semver:* label on the merged PR, auto-propagates the version pins into a tatara-helmfile PR, coalesces sibling components into a deploy train, and lets the operator close the originating issue on apply. tatara-helmfile pins the chart version and the image tag independently - an image-only update does not require a chart version bump, and vice versa.

The legacy 0.0.0-g<sha> pre-release scheme (the g prefix avoids an all-digit leading segment failing helm package semver validation) is still packaged on every push to main, but the deployed pins are the bare-semver releases, not the per-commit charts.