# cubiculum-ai/tractanda architecture

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

- Interactive diagram: https://gitdiagram.com/cubiculum-ai/tractanda
- Repository: https://github.com/cubiculum-ai/tractanda

## Overview

Tractanda is a local, shared knowledge-base service: people and agents submit item edits or queries through clients; the service enforces current permissions, manages versioned revisions, and returns results. Its domain includes category hierarchies and saved or transient views, with lexical and optional semantic retrieval. The graph also shows the documented CLI, terminal, MCP, daemon, and browser surfaces. Some subsystem wiring is inferred only from README-level capability descriptions; optional embedding integration is shown separately.

Main entry points: [`Sources/TractandaCore/Service.swift`](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Service.swift) (Item service), [`Sources/TractandaCore/Query.swift`](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Query.swift) (Views and queries), [`Sources/TractandaCore/SemanticService.swift`](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/SemanticService.swift) (Semantic retrieval), [`Packages/TractandaClient/Sources/TractandaClient/ItemClient.swift`](https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaClient/Sources/TractandaClient/ItemClient.swift) (Typed item client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_cli["CLI<br/>[main.swift]"]
  node_tui["Terminal UI"]
  node_item_client["Typed item client<br/>[ItemClient.swift]"]
  node_kanban["Kanban repository"]
  node_web["Browser Kanban<br/>[KanbanPage.swift]"]
end

subgraph group_service["Core service"]
  node_item_service["Item service<br/>[Service.swift]"]
  node_authorization["Access control"]
  node_store[("Revision store<br/>[Store.swift]")]
  node_categories["Category hierarchy"]
end

subgraph group_retrieval["Query and semantics"]
  node_query["Views and queries<br/>[Query.swift]"]
  node_semantic_service["Semantic retrieval"]
  node_vector_storage[("Vector index bridge")]
end

subgraph group_interfaces["Service interfaces"]
  node_local_transport["Native transport"]
  node_daemon["Shared daemon"]
  node_mcp_stdio["Stdio MCP"]
  node_mcp_http["HTTP MCP"]
end

subgraph group_optional["Optional integrations"]
  node_embedding_host["Embedding host<br/>[main.swift]"]
  node_embedding_engine["Embedding engine"]
end

node_people_agents(("People and agents"))

node_people_agents -->|"use"| node_cli
node_people_agents -->|"use"| node_tui
node_people_agents -->|"use"| node_web
node_cli -->|"send requests"| node_local_transport
node_tui -->|"edit and query"| node_item_client
node_web -->|"present board"| node_kanban
node_kanban -->|"query items"| node_item_client
node_item_client -->|"send requests"| node_local_transport
node_local_transport -->|"dispatch"| node_item_service
node_daemon -->|"serve requests"| node_item_service
node_mcp_stdio -->|"dispatch tools"| node_item_service
node_mcp_http -->|"dispatch tools"| node_item_service
node_item_service -->|"authorize requests"| node_authorization
node_item_service -->|"read and write revisions"| node_store
node_item_service -->|"run queries"| node_query
node_query -->|"read revisions"| node_store
node_query -->|"resolve categories"| node_categories
node_item_service -->|"provide semantic retrieval"| node_semantic_service
node_semantic_service -->|"search and maintain index"| node_vector_storage
node_embedding_host -->|"serve embeddings"| node_embedding_engine
node_semantic_service -.->|"request embeddings"| node_embedding_host

click node_cli "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCLI/main.swift"
click node_tui "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaTUI/TerminalApplication.swift"
click node_item_client "https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaClient/Sources/TractandaClient/ItemClient.swift"
click node_kanban "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaKanban/KanbanRepository.swift"
click node_web "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaWeb/KanbanPage.swift"
click node_item_service "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Service.swift"
click node_authorization "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/AccessControl.swift"
click node_store "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Store.swift"
click node_categories "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/CategoryHierarchy.swift"
click node_query "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Query.swift"
click node_semantic_service "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/SemanticService.swift"
click node_vector_storage "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/SemanticVec1Storage.swift"
click node_local_transport "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/LocalItemTransport.swift"
click node_daemon "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaServer/DaemonApplication.swift"
click node_mcp_stdio "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaMCP/StandardIOTransport.swift"
click node_mcp_http "https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaMCP/MCPHTTPService.swift"
click node_embedding_host "https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaEmbeddings/Sources/TractandaEmbeddingsHost/main.swift"
click node_embedding_engine "https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaEmbeddings/Sources/TractandaEmbeddingsHost/EmbeddingEngine.swift"

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_cli,node_tui,node_item_client,node_kanban,node_web toneBlue
class node_item_service,node_authorization,node_store,node_categories toneAmber
class node_query,node_semantic_service,node_vector_storage toneMint
class node_local_transport,node_daemon,node_mcp_stdio,node_mcp_http toneRose
class node_embedding_host,node_embedding_engine,node_people_agents toneIndigo
```

## Components

### User clients

- [CLI](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCLI/main.swift): `Sources/TractandaCLI/main.swift`
- [Terminal UI](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaTUI/TerminalApplication.swift): `Sources/TractandaTUI/TerminalApplication.swift`
- [Typed item client](https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaClient/Sources/TractandaClient/ItemClient.swift): `Packages/TractandaClient/Sources/TractandaClient/ItemClient.swift`
- [Kanban repository](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaKanban/KanbanRepository.swift): `Sources/TractandaKanban/KanbanRepository.swift`
- [Browser Kanban](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaWeb/KanbanPage.swift): `Sources/TractandaWeb/KanbanPage.swift`

### Core service

- [Item service](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Service.swift): `Sources/TractandaCore/Service.swift`
- [Access control](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/AccessControl.swift): `Sources/TractandaCore/AccessControl.swift`
- [Revision store](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Store.swift): `Sources/TractandaCore/Store.swift`
- [Category hierarchy](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/CategoryHierarchy.swift): `Sources/TractandaCore/CategoryHierarchy.swift`

### Query and semantics

- [Views and queries](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/Query.swift): `Sources/TractandaCore/Query.swift`
- [Semantic retrieval](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/SemanticService.swift): `Sources/TractandaCore/SemanticService.swift`
- [Vector index bridge](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/SemanticVec1Storage.swift): `Sources/TractandaCore/SemanticVec1Storage.swift`

### Service interfaces

- [Native transport](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaCore/LocalItemTransport.swift): `Sources/TractandaCore/LocalItemTransport.swift`
- [Shared daemon](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaServer/DaemonApplication.swift): `Sources/TractandaServer/DaemonApplication.swift`
- [Stdio MCP](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaMCP/StandardIOTransport.swift): `Sources/TractandaMCP/StandardIOTransport.swift`
- [HTTP MCP](https://github.com/cubiculum-ai/tractanda/blob/main/Sources/TractandaMCP/MCPHTTPService.swift): `Sources/TractandaMCP/MCPHTTPService.swift`

### Optional integrations

- [Embedding host](https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaEmbeddings/Sources/TractandaEmbeddingsHost/main.swift): `Packages/TractandaEmbeddings/Sources/TractandaEmbeddingsHost/main.swift`
- [Embedding engine](https://github.com/cubiculum-ai/tractanda/blob/main/Packages/TractandaEmbeddings/Sources/TractandaEmbeddingsHost/EmbeddingEngine.swift): `Packages/TractandaEmbeddings/Sources/TractandaEmbeddingsHost/EmbeddingEngine.swift`

### Other components

- **People and agents**

## Connections

- People and agents → CLI: use
- People and agents → Terminal UI: use
- People and agents → Browser Kanban: use
- CLI → Native transport: send requests
- Terminal UI → Typed item client: edit and query
- Browser Kanban → Kanban repository: present board
- Kanban repository → Typed item client: query items
- Typed item client → Native transport: send requests
- Native transport → Item service: dispatch
- Shared daemon → Item service: serve requests
- Stdio MCP → Item service: dispatch tools
- HTTP MCP → Item service: dispatch tools
- Item service → Access control: authorize requests
- Item service → Revision store: read and write revisions
- Item service → Views and queries: run queries
- Views and queries → Revision store: read revisions
- Views and queries → Category hierarchy: resolve categories
- Item service → Semantic retrieval: provide semantic retrieval
- Semantic retrieval → Vector index bridge: search and maintain index
- Embedding host → Embedding engine: serve embeddings
- Semantic retrieval → Embedding host: request embeddings