# cmsued/gentle-ai architecture

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

- Interactive diagram: https://gitdiagram.com/cmsued/gentle-ai
- Repository: https://github.com/cmsued/gentle-ai

## Overview

Gentle-AI is a Go CLI and terminal application that adds deterministic configuration, memory, workflows, and review evidence to existing AI coding agents. The main user path enters through the CLI, then configures or synchronizes agent integrations; separate workflows support evidence-based review and persistent project context. Telemetry is a distinct collector service. The graph combines sampled call/reference evidence with README-documented capabilities; several subsystem internals were not sampled, so their connections are documented rather than asserted as inspected implementation calls.

Main entry points: [`internal/cli/install.go`](https://github.com/cmsued/gentle-ai/blob/main/internal/cli/install.go) (Install and sync), [`internal/app/app.go`](https://github.com/cmsued/gentle-ai/blob/main/internal/app/app.go) (Command dispatcher), [`internal/cli/review_lens_context.go`](https://github.com/cmsued/gentle-ai/blob/main/internal/cli/review_lens_context.go) (Review workflow), [`cmd/gentle-ai/main.go`](https://github.com/cmsued/gentle-ai/blob/main/cmd/gentle-ai/main.go) (Gentle-AI CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["CLI and interaction"]
  node_cli["Gentle-AI CLI<br/>[main.go]"]
  node_app["Command dispatcher<br/>[app.go]"]
  node_tui["Terminal interface<br/>[router.go]"]
end

subgraph group_environment["Agent environment"]
  node_install["Install and sync<br/>[install.go]"]
  node_planner["Install planning<br/>[resolver.go]"]
  node_adapters["Agent adapters<br/>[registry.go]"]
  node_guidance["Guidance injection<br/>[orchestrator.go]"]
  node_state[("User state<br/>[state.go]")]
  node_backups["Backup and restore<br/>[restore.go]"]
end

subgraph group_workflow["Memory and review"]
  node_review["Review workflow"]
  node_reviewer["Reviewer providers<br/>[contract.go]"]
  node_transactions[("Review transactions<br/>[store.go]")]
  node_engram["Engram memory<br/>[inject.go]"]
  node_odd["ODD guidance<br/>[routing.go]"]
end

subgraph group_telemetry["Telemetry services"]
  node_telemetry["Agent telemetry<br/>[runtime.go]"]
  node_collector["Telemetry collector<br/>[main.go]"]
  node_collectorstore[("Collector storage<br/>[runtime_storage.go]")]
end

node_user(("Developer"))
node_agents{{"Installed agents"}}

node_user -->|"runs"| node_cli
node_cli -->|"starts"| node_app
node_app -->|"launches"| node_tui
node_app -->|"dispatches"| node_install
node_install -.->|"resolves plan"| node_planner
node_install -.->|"configures"| node_adapters
node_install -.->|"installs components"| node_guidance
node_install -->|"persists selection"| node_state
node_install -.->|"snapshots changes"| node_backups
node_guidance -.->|"injects guidance"| node_agents
node_user -.->|"requests review"| node_review
node_review -.->|"invokes provider"| node_reviewer
node_review -->|"records authority"| node_transactions
node_engram -.->|"provides memory"| node_agents
node_odd -.->|"guides workflow"| node_agents
node_agents -.->|"emits events"| node_telemetry
node_collector -->|"stores events"| node_collectorstore
node_telemetry -.->|"sends events"| node_collector

click node_cli "https://github.com/cmsued/gentle-ai/blob/main/cmd/gentle-ai/main.go"
click node_app "https://github.com/cmsued/gentle-ai/blob/main/internal/app/app.go"
click node_tui "https://github.com/cmsued/gentle-ai/blob/main/internal/tui/router.go"
click node_install "https://github.com/cmsued/gentle-ai/blob/main/internal/cli/install.go"
click node_planner "https://github.com/cmsued/gentle-ai/blob/main/internal/planner/resolver.go"
click node_adapters "https://github.com/cmsued/gentle-ai/blob/main/internal/agents/registry.go"
click node_guidance "https://github.com/cmsued/gentle-ai/blob/main/internal/components/agentguidance/orchestrator.go"
click node_state "https://github.com/cmsued/gentle-ai/blob/main/internal/state/state.go"
click node_backups "https://github.com/cmsued/gentle-ai/blob/main/internal/backup/restore.go"
click node_review "https://github.com/cmsued/gentle-ai/blob/main/internal/cli/review_lens_context.go"
click node_reviewer "https://github.com/cmsued/gentle-ai/blob/main/internal/reviewerprovider/contract.go"
click node_transactions "https://github.com/cmsued/gentle-ai/blob/main/internal/reviewtransaction/store.go"
click node_engram "https://github.com/cmsued/gentle-ai/blob/main/internal/components/engram/inject.go"
click node_odd "https://github.com/cmsued/gentle-ai/blob/main/internal/components/agentguidance/routing.go"
click node_telemetry "https://github.com/cmsued/gentle-ai/blob/main/internal/telemetry/runtime.go"
click node_collector "https://github.com/cmsued/gentle-ai/blob/main/cmd/gentle-telemetry/main.go"
click node_collectorstore "https://github.com/cmsued/gentle-ai/blob/main/internal/telemetrycollector/runtime_storage.go"

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_app,node_tui toneBlue
class node_install,node_planner,node_adapters,node_guidance,node_state,node_backups toneAmber
class node_review,node_reviewer,node_transactions,node_engram,node_odd toneMint
class node_telemetry,node_collector,node_collectorstore toneRose
class node_user,node_agents toneIndigo
```

## Components

### CLI and interaction

- [Gentle-AI CLI](https://github.com/cmsued/gentle-ai/blob/main/cmd/gentle-ai/main.go): `cmd/gentle-ai/main.go`
- [Command dispatcher](https://github.com/cmsued/gentle-ai/blob/main/internal/app/app.go): `internal/app/app.go`
- [Terminal interface](https://github.com/cmsued/gentle-ai/blob/main/internal/tui/router.go): `internal/tui/router.go`

### Agent environment

- [Install and sync](https://github.com/cmsued/gentle-ai/blob/main/internal/cli/install.go): `internal/cli/install.go`
- [Install planning](https://github.com/cmsued/gentle-ai/blob/main/internal/planner/resolver.go): `internal/planner/resolver.go`
- [Agent adapters](https://github.com/cmsued/gentle-ai/blob/main/internal/agents/registry.go): `internal/agents/registry.go`
- [Guidance injection](https://github.com/cmsued/gentle-ai/blob/main/internal/components/agentguidance/orchestrator.go): `internal/components/agentguidance/orchestrator.go`
- [User state](https://github.com/cmsued/gentle-ai/blob/main/internal/state/state.go): `internal/state/state.go`
- [Backup and restore](https://github.com/cmsued/gentle-ai/blob/main/internal/backup/restore.go): `internal/backup/restore.go`

### Memory and review

- [Review workflow](https://github.com/cmsued/gentle-ai/blob/main/internal/cli/review_lens_context.go): `internal/cli/review_lens_context.go`
- [Reviewer providers](https://github.com/cmsued/gentle-ai/blob/main/internal/reviewerprovider/contract.go): `internal/reviewerprovider/contract.go`
- [Review transactions](https://github.com/cmsued/gentle-ai/blob/main/internal/reviewtransaction/store.go): `internal/reviewtransaction/store.go`
- [Engram memory](https://github.com/cmsued/gentle-ai/blob/main/internal/components/engram/inject.go): `internal/components/engram/inject.go`
- [ODD guidance](https://github.com/cmsued/gentle-ai/blob/main/internal/components/agentguidance/routing.go): `internal/components/agentguidance/routing.go`

### Telemetry services

- [Agent telemetry](https://github.com/cmsued/gentle-ai/blob/main/internal/telemetry/runtime.go): `internal/telemetry/runtime.go`
- [Telemetry collector](https://github.com/cmsued/gentle-ai/blob/main/cmd/gentle-telemetry/main.go): `cmd/gentle-telemetry/main.go`
- [Collector storage](https://github.com/cmsued/gentle-ai/blob/main/internal/telemetrycollector/runtime_storage.go): `internal/telemetrycollector/runtime_storage.go`

### Other components

- **Developer**
- **Installed agents**

## Connections

- Developer → Gentle-AI CLI: runs (evidence: `cmd/gentle-ai/main.go`)
- Gentle-AI CLI → Command dispatcher: starts (evidence: `cmd/gentle-ai/main.go`)
- Command dispatcher → Terminal interface: launches (evidence: `internal/app/app.go`)
- Command dispatcher → Install and sync: dispatches (evidence: `internal/app/app.go`)
- Install and sync → Install planning: resolves plan
- Install and sync → Agent adapters: configures
- Install and sync → Guidance injection: installs components
- Install and sync → User state: persists selection
- Install and sync → Backup and restore: snapshots changes
- Guidance injection → Installed agents: injects guidance
- Developer → Review workflow: requests review (evidence: `README.md`)
- Review workflow → Reviewer providers: invokes provider
- Review workflow → Review transactions: records authority (evidence: `internal/cli/review_lens_context.go`)
- Engram memory → Installed agents: provides memory (evidence: `README.md`)
- ODD guidance → Installed agents: guides workflow (evidence: `README.md`)
- Installed agents → Agent telemetry: emits events
- Telemetry collector → Collector storage: stores events (evidence: `cmd/gentle-telemetry/main.go`)
- Agent telemetry → Telemetry collector: sends events
