# rjustyn1/tikitaka architecture

> Architecture diagram of the GitHub repository rjustyn1/tikitaka, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rjustyn1/tikitaka
- Repository: https://github.com/rjustyn1/tikitaka

## Overview

Tiki-Taka is a single-user, multi-agent coding platform whose central workflow plans and runs shared-team tasks, captures their traces, then governs which extracted memories reach each agent. Its React UI calls a Fastify control plane; server orchestration coordinates planning, leased agent execution, and memory processing. The memory path segments captured work, extracts notes, routes them by recognition, checks safety, reviews or quarantines them, lands approved files, and records grants or denials. README documents major capabilities not fully visible in the sampled source; links for those are shown only where documented wiring supports them.

Main entry points: [`apps/server/src/agent-service.ts`](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/agent-service.ts) (Agent service), [`apps/server/src/memory/pipeline.ts`](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/pipeline.ts) (Memory pipeline), [`apps/server/src/memory/group-runner.ts`](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/group-runner.ts) (Group orchestration), [`apps/server/src/store.ts`](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/store.ts) (JSON store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator UI"]
  node_web["Web workspace<br/>[App.tsx]"]
  node_webhooks["Group task views<br/>[useGroupTask.ts]"]
  node_webmemory["Memory views<br/>[useMemoryStatus.ts]"]
  node_api["HTTP client<br/>[api.ts]"]
end

subgraph group_control["Control plane"]
  node_server["HTTP routes<br/>[app.ts]"]
  node_service["Agent service<br/>[agent-service.ts]"]
end

subgraph group_execution["Task execution"]
  node_groups["Group orchestration<br/>[group-runner.ts]"]
  node_planner["Task planner<br/>[planner.ts]"]
  node_runner["Agent runner<br/>[runner-factory.ts]"]
  node_codex["Codex session<br/>[codex-runner.ts]"]
  node_trace["Trace summaries<br/>[trace-summary.ts]"]
end

subgraph group_governance["Memory governance"]
  node_pipeline["Memory pipeline<br/>[pipeline.ts]"]
  node_segments["Topic segments<br/>[topic-segment.ts]"]
  node_buffer["Segment buffers<br/>[task-buffer.ts]"]
  node_consolidator["Note extraction<br/>[consolidator.ts]"]
  node_extractor["Extractor client"]
  node_recognizer["Recipient recognition<br/>[recognizer.ts]"]
  node_safety["Safety checks<br/>[safety.ts]"]
  node_review["Review decisions<br/>[review.ts]"]
  node_landing["Memory landing<br/>[landing.ts]"]
end

subgraph group_state["State and workspaces"]
  node_ledger["Grant ledger<br/>[ledger.ts]"]
  node_store[("JSON store<br/>[store.ts]")]
  node_workspace["Agent workspaces<br/>[workspace.ts]"]
end

node_user(("Operator"))
node_ark{{"Ark model API"}}
node_codexruntime{{"Codex runtime"}}

node_user -->|"operates"| node_web
node_web -->|"requests"| node_api
node_webhooks -->|"polls tasks"| node_api
node_webmemory -->|"polls status"| node_api
node_api -->|"HTTP calls"| node_server
node_server -->|"dispatches"| node_service
node_service -->|"reads/writes"| node_store
node_service -->|"initializes"| node_workspace
node_service -->|"starts tasks"| node_groups
node_groups -->|"plans DAG"| node_planner
node_groups -->|"runs nodes"| node_runner
node_runner -->|"starts sessions"| node_codex
node_codex -->|"executes"| node_codexruntime
node_groups -->|"records traces"| node_store
node_groups -->|"flushes memory"| node_pipeline
node_pipeline -->|"builds buffers"| node_buffer
node_buffer -->|"reads spans"| node_store
node_pipeline -->|"extracts notes"| node_consolidator
node_consolidator -->|"requests extraction"| node_extractor
node_extractor -.->|"calls model"| node_ark
node_pipeline -->|"routes recipients"| node_recognizer
node_pipeline -->|"checks notes"| node_safety
node_pipeline -->|"processes candidates"| node_review
node_review -->|"lands or revokes"| node_landing
node_review -->|"records decisions"| node_ledger
node_review -->|"updates notes"| node_store
node_landing -->|"writes files"| node_workspace
node_ledger -->|"appends records"| node_store
node_service -->|"serves memory views"| node_landing
node_service -->|"serves audit views"| node_ledger

click node_web "https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/App.tsx"
click node_webhooks "https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/group/useGroupTask.ts"
click node_webmemory "https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/group/useMemoryStatus.ts"
click node_api "https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/api.ts"
click node_server "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/app.ts"
click node_service "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/agent-service.ts"
click node_groups "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/group-runner.ts"
click node_planner "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/planner.ts"
click node_runner "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/runner-factory.ts"
click node_codex "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/codex-runner.ts"
click node_trace "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/trace-summary.ts"
click node_pipeline "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/pipeline.ts"
click node_segments "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/topic-segment.ts"
click node_buffer "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/task-buffer.ts"
click node_consolidator "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/consolidator.ts"
click node_extractor "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/extractor-client.ts"
click node_recognizer "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/recognizer.ts"
click node_safety "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/safety.ts"
click node_review "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/review.ts"
click node_landing "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/landing.ts"
click node_ledger "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/ledger.ts"
click node_store "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/store.ts"
click node_workspace "https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/workspace.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_webhooks,node_webmemory,node_api toneBlue
class node_server,node_service toneAmber
class node_groups,node_planner,node_runner,node_codex,node_trace,node_ark toneMint
class node_pipeline,node_segments,node_buffer,node_consolidator,node_extractor,node_recognizer,node_safety,node_review,node_landing toneRose
class node_ledger,node_store,node_workspace,node_user,node_codexruntime toneIndigo
```

## Components

### Operator UI

- [Web workspace](https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Group task views](https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/group/useGroupTask.ts): `apps/web/src/group/useGroupTask.ts`
- [Memory views](https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/group/useMemoryStatus.ts): `apps/web/src/group/useMemoryStatus.ts`
- [HTTP client](https://github.com/rjustyn1/tikitaka/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`

### Control plane

- [HTTP routes](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/app.ts): `apps/server/src/app.ts`
- [Agent service](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/agent-service.ts): `apps/server/src/agent-service.ts`

### Task execution

- [Group orchestration](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/group-runner.ts): `apps/server/src/memory/group-runner.ts`
- [Task planner](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/planner.ts): `apps/server/src/memory/planner.ts`
- [Agent runner](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/runner-factory.ts): `apps/server/src/runner-factory.ts`
- [Codex session](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/codex-runner.ts): `apps/server/src/codex-runner.ts`
- [Trace summaries](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/trace-summary.ts): `apps/server/src/trace-summary.ts`

### Memory governance

- [Memory pipeline](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/pipeline.ts): `apps/server/src/memory/pipeline.ts`
- [Topic segments](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/topic-segment.ts): `apps/server/src/memory/topic-segment.ts`
- [Segment buffers](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/task-buffer.ts): `apps/server/src/memory/task-buffer.ts`
- [Note extraction](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/consolidator.ts): `apps/server/src/memory/consolidator.ts`
- [Extractor client](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/extractor-client.ts): `apps/server/src/memory/extractor-client.ts`
- [Recipient recognition](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/recognizer.ts): `apps/server/src/memory/recognizer.ts`
- [Safety checks](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/safety.ts): `apps/server/src/memory/safety.ts`
- [Review decisions](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/review.ts): `apps/server/src/memory/review.ts`
- [Memory landing](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/landing.ts): `apps/server/src/memory/landing.ts`

### State and workspaces

- [Grant ledger](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/memory/ledger.ts): `apps/server/src/memory/ledger.ts`
- [JSON store](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/store.ts): `apps/server/src/store.ts`
- [Agent workspaces](https://github.com/rjustyn1/tikitaka/blob/main/apps/server/src/workspace.ts): `apps/server/src/workspace.ts`

### Other components

- **Operator**
- **Ark model API**
- **Codex runtime**

## Connections

- Operator → Web workspace: operates
- Web workspace → HTTP client: requests
- Group task views → HTTP client: polls tasks
- Memory views → HTTP client: polls status
- HTTP client → HTTP routes: HTTP calls
- HTTP routes → Agent service: dispatches
- Agent service → JSON store: reads/writes
- Agent service → Agent workspaces: initializes
- Agent service → Group orchestration: starts tasks
- Group orchestration → Task planner: plans DAG
- Group orchestration → Agent runner: runs nodes
- Agent runner → Codex session: starts sessions
- Codex session → Codex runtime: executes
- Group orchestration → JSON store: records traces
- Group orchestration → Memory pipeline: flushes memory
- Memory pipeline → Segment buffers: builds buffers
- Segment buffers → JSON store: reads spans
- Memory pipeline → Note extraction: extracts notes
- Note extraction → Extractor client: requests extraction
- Extractor client → Ark model API: calls model
- Memory pipeline → Recipient recognition: routes recipients
- Memory pipeline → Safety checks: checks notes
- Memory pipeline → Review decisions: processes candidates
- Review decisions → Memory landing: lands or revokes
- Review decisions → Grant ledger: records decisions
- Review decisions → JSON store: updates notes
- Memory landing → Agent workspaces: writes files
- Grant ledger → JSON store: appends records
- Agent service → Memory landing: serves memory views
- Agent service → Grant ledger: serves audit views