# woonyong-choi/saturn architecture

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

- Interactive diagram: https://gitdiagram.com/woonyong-choi/saturn
- Repository: https://github.com/woonyong-choi/saturn

## Overview

Saturn is a terminal chat tool that preserves one local conversation across Codex and Claude Code sessions. The user starts or resumes a chat in the CLI/TUI, sends requests that the engine records and routes to a provider, then sees results and can switch providers while retaining context. Other documented capabilities include follow-up routing, queued tasks, context handoff, permission prompts, chat export/pruning, and router training/version management. Edges follow the README’s designed workflow and the shown CLI/TUI excerpts; unsampled implementation details are not treated as verified calls.

Main entry points: [`saturn-terminal/cli/src/main.rs`](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/cli/src/main.rs) (CLI commands), [`saturn-terminal/engine/src/main.rs`](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/main.rs) (Engine runtime), [`saturn-protocol/src/rpc.rs`](https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/rpc.rs) (Protocol messages), [`saturn-terminal/tui/src/app.rs`](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/app.rs) (Chat TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_tui["Chat TUI<br/>[app.rs]"]
  node_screens["TUI screens"]
  node_keys["Key handling<br/>[mod.rs]"]
  node_i18n["Localization<br/>[i18n.rs]"]
end

subgraph group_engine["Engine workflow"]
  node_protocol["Protocol messages<br/>[rpc.rs]"]
  node_identifiers["Protocol IDs<br/>[ids.rs]"]
  node_input_types["Input types<br/>[input.rs]"]
  node_engine_runtime["Engine runtime<br/>[main.rs]"]
  node_intake["Input intake<br/>[intake.rs]"]
  node_dispatch["Request dispatch<br/>[dispatch.rs]"]
end

subgraph group_context["Context and policy"]
  node_router["Follow-up router<br/>[mod.rs]"]
  node_tasks["Task queue<br/>[tasks.rs]"]
  node_context_packet["Context packets<br/>[context.rs]"]
  node_permissions["Permission rules<br/>[mod.rs]"]
  node_sessions["Provider sessions<br/>[sessions.rs]"]
  node_training["Router training<br/>[trainer.rs]"]
end

subgraph group_providers["Provider integration"]
  node_provider_adapter["Provider adapters<br/>[adapter.rs]"]
end

subgraph group_persistence["Local records"]
  node_store[("SQLite record store<br/>[records.rs]")]
end

node_user(("Developer"))
node_codex["Codex CLI"]
node_claude["Claude Code"]

node_user -->|"runs commands"| node_cli
node_cli -->|"starts and connects"| node_engine_runtime
node_cli -->|"opens chat"| node_tui
node_tui -->|"renders screens"| node_screens
node_tui -->|"resolves keys"| node_keys
node_cli -->|"sends requests"| node_protocol
node_tui -->|"sends attach"| node_protocol
node_engine_runtime -.->|"serves requests"| node_protocol
node_protocol -->|"uses IDs"| node_identifiers
node_protocol -->|"uses input types"| node_input_types
node_engine_runtime -.->|"accepts input"| node_intake
node_intake -->|"records input"| node_store
node_intake -->|"routes follow-ups"| node_router
node_intake -->|"queues tasks"| node_tasks
node_engine_runtime -.->|"dispatches work"| node_dispatch
node_dispatch -->|"sends requests"| node_provider_adapter
node_provider_adapter -->|"invokes provider"| node_codex
node_provider_adapter -->|"invokes provider"| node_claude
node_dispatch -->|"checks permissions"| node_permissions
node_dispatch -->|"manages sessions"| node_sessions
node_sessions -->|"builds handoff"| node_context_packet
node_context_packet -->|"reads conversation record"| node_store
node_cli -.->|"requests training"| node_training
node_engine_runtime -->|"persists records"| node_store

click node_cli "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/cli/src/main.rs"
click node_tui "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/app.rs"
click node_screens "https://github.com/woonyong-choi/saturn/tree/main/saturn-terminal/tui/src/view"
click node_keys "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/keymap/mod.rs"
click node_i18n "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/i18n.rs"
click node_protocol "https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/rpc.rs"
click node_identifiers "https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/ids.rs"
click node_input_types "https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/input.rs"
click node_engine_runtime "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/main.rs"
click node_intake "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/intake.rs"
click node_dispatch "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/dispatch.rs"
click node_router "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/routers/mod.rs"
click node_tasks "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/queue/tasks.rs"
click node_context_packet "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/sessions/context.rs"
click node_permissions "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/permission/mod.rs"
click node_sessions "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/sessions.rs"
click node_provider_adapter "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/providers/adapter.rs"
click node_store "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/store/records.rs"
click node_training "https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/training/trainer.rs"

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_screens,node_keys,node_i18n toneBlue
class node_protocol,node_identifiers,node_input_types,node_engine_runtime,node_intake,node_dispatch toneAmber
class node_router,node_tasks,node_context_packet,node_permissions,node_sessions,node_training toneMint
class node_provider_adapter toneRose
class node_store,node_user,node_codex,node_claude toneIndigo
```

## Components

### User interface

- [CLI commands](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/cli/src/main.rs): `saturn-terminal/cli/src/main.rs`
- [Chat TUI](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/app.rs): `saturn-terminal/tui/src/app.rs`
- [TUI screens](https://github.com/woonyong-choi/saturn/tree/main/saturn-terminal/tui/src/view): `saturn-terminal/tui/src/view`
- [Key handling](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/keymap/mod.rs): `saturn-terminal/tui/src/keymap/mod.rs`
- [Localization](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/tui/src/i18n.rs): `saturn-terminal/tui/src/i18n.rs`

### Engine workflow

- [Protocol messages](https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/rpc.rs): `saturn-protocol/src/rpc.rs`
- [Protocol IDs](https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/ids.rs): `saturn-protocol/src/ids.rs`
- [Input types](https://github.com/woonyong-choi/saturn/blob/main/saturn-protocol/src/input.rs): `saturn-protocol/src/input.rs`
- [Engine runtime](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/main.rs): `saturn-terminal/engine/src/main.rs`
- [Input intake](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/intake.rs): `saturn-terminal/engine/src/intake.rs`
- [Request dispatch](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/dispatch.rs): `saturn-terminal/engine/src/dispatch.rs`

### Context and policy

- [Follow-up router](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/routers/mod.rs): `saturn-terminal/core/src/routers/mod.rs`
- [Task queue](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/queue/tasks.rs): `saturn-terminal/core/src/queue/tasks.rs`
- [Context packets](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/sessions/context.rs): `saturn-terminal/core/src/sessions/context.rs`
- [Permission rules](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/core/src/permission/mod.rs): `saturn-terminal/core/src/permission/mod.rs`
- [Provider sessions](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/sessions.rs): `saturn-terminal/engine/src/sessions.rs`
- [Router training](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/training/trainer.rs): `saturn-terminal/engine/src/training/trainer.rs`

### Provider integration

- [Provider adapters](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/providers/adapter.rs): `saturn-terminal/engine/src/providers/adapter.rs`

### Local records

- [SQLite record store](https://github.com/woonyong-choi/saturn/blob/main/saturn-terminal/engine/src/store/records.rs): `saturn-terminal/engine/src/store/records.rs`

### Other components

- **Developer**
- **Codex CLI**
- **Claude Code**

## Connections

- Developer → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Engine runtime: starts and connects (evidence: `README.md`)
- CLI commands → Chat TUI: opens chat (evidence: `saturn-terminal/cli/src/main.rs`)
- Chat TUI → TUI screens: renders screens (evidence: `saturn-terminal/tui/src/app.rs`)
- Chat TUI → Key handling: resolves keys (evidence: `saturn-terminal/tui/src/app.rs`)
- CLI commands → Protocol messages: sends requests (evidence: `saturn-terminal/cli/src/main.rs`)
- Chat TUI → Protocol messages: sends attach (evidence: `saturn-terminal/tui/src/app.rs`)
- Engine runtime → Protocol messages: serves requests
- Protocol messages → Protocol IDs: uses IDs (evidence: `saturn-protocol/src/rpc.rs`)
- Protocol messages → Input types: uses input types (evidence: `saturn-protocol/src/rpc.rs`)
- Engine runtime → Input intake: accepts input
- Input intake → SQLite record store: records input (evidence: `README.md`)
- Input intake → Follow-up router: routes follow-ups (evidence: `README.md`)
- Input intake → Task queue: queues tasks (evidence: `README.md`)
- Engine runtime → Request dispatch: dispatches work
- Request dispatch → Provider adapters: sends requests (evidence: `README.md`)
- Provider adapters → Codex CLI: invokes provider (evidence: `README.md`)
- Provider adapters → Claude Code: invokes provider (evidence: `README.md`)
- Request dispatch → Permission rules: checks permissions (evidence: `README.md`)
- Request dispatch → Provider sessions: manages sessions (evidence: `README.md`)
- Provider sessions → Context packets: builds handoff (evidence: `README.md`)
- Context packets → SQLite record store: reads conversation record (evidence: `README.md`)
- CLI commands → Router training: requests training
- Engine runtime → SQLite record store: persists records (evidence: `README.md`)
