# alstes/todomate-cli architecture

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

- Interactive diagram: https://gitdiagram.com/alstes/todomate-cli
- Repository: https://github.com/alstes/todomate-cli

## Overview

TodoMate CLI is a native terminal client for managing todos, goals, and vision through TodoMate’s API. The principal path is command parsing and dispatch, domain-specific command handling, authenticated API requests, then human-readable or JSON output. Authentication obtains a GitHub token, exchanges it with the API using a user-provided API key, and stores credentials; configuration is handled locally. The README also describes the broader Vision → Goals → Todos product hierarchy and private GitHub-repository data ownership, but those backend storage details are outside this CLI’s sampled implementation. Device flow is documented as not yet implemented.

Main entry points: [`src/api/mod.rs`](https://github.com/alstes/todomate-cli/blob/main/src/api/mod.rs) (API client), [`src/main.rs`](https://github.com/alstes/todomate-cli/blob/main/src/main.rs) (Runtime dispatcher), [`src/auth/mod.rs`](https://github.com/alstes/todomate-cli/blob/main/src/auth/mod.rs) (Authentication flow), [`src/output.rs`](https://github.com/alstes/todomate-cli/blob/main/src/output.rs) (Text and JSON output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry and configuration"]
  node_parser["Command parser<br/>[cli.rs]"]
  node_dispatcher["Runtime dispatcher<br/>[main.rs]"]
  node_config["Local configuration<br/>[config.rs]"]
end

subgraph group_domain["TodoMate domain commands"]
  node_todos["Todo commands<br/>[todos.rs]"]
  node_goals["Goal commands<br/>[goals.rs]"]
  node_vision["Vision commands<br/>[vision.rs]"]
end

subgraph group_services["API and authentication"]
  node_api["API client<br/>[mod.rs]"]
  node_models["API data models<br/>[models.rs]"]
  node_auth["Authentication flow<br/>[mod.rs]"]
  node_gh_token["GitHub token lookup<br/>[gh_token.rs]"]
  node_device_flow["Device flow stub<br/>[device_flow.rs]"]
end

subgraph group_presentation["Output and local credentials"]
  node_output["Text and JSON output<br/>[output.rs]"]
  node_credentials[("Credential storage<br/>[token_store.rs]")]
end

node_user(("Terminal user"))
node_github_cli["GitHub CLI"]
node_todo_api{{"TodoMate API"}}
node_credential_store[("OS keychain or file")]

node_user -->|"enters commands"| node_parser
node_parser -->|"parsed arguments"| node_dispatcher
node_dispatcher -->|"loads or updates"| node_config
node_dispatcher -->|"routes auth"| node_auth
node_dispatcher -->|"routes todos"| node_todos
node_dispatcher -->|"routes goals"| node_goals
node_dispatcher -->|"routes vision"| node_vision
node_auth -->|"gets token"| node_gh_token
node_gh_token -->|"reads token"| node_github_cli
node_auth -->|"exchanges credentials"| node_api
node_auth -->|"saves or checks"| node_credentials
node_credentials -->|"persists credentials"| node_credential_store
node_api -->|"loads refresh credentials"| node_credentials
node_todos -->|"requests todo operations"| node_api
node_goals -->|"requests goal operations"| node_api
node_vision -->|"requests vision operations"| node_api
node_api -->|"sends HTTP requests"| node_todo_api
node_api -->|"serializes and parses"| node_models
node_todos -->|"formats results"| node_output
node_goals -->|"formats results"| node_output
node_vision -->|"formats results"| node_output
node_output -->|"renders domain values"| node_models

click node_parser "https://github.com/alstes/todomate-cli/blob/main/src/cli.rs"
click node_dispatcher "https://github.com/alstes/todomate-cli/blob/main/src/main.rs"
click node_config "https://github.com/alstes/todomate-cli/blob/main/src/config.rs"
click node_todos "https://github.com/alstes/todomate-cli/blob/main/src/commands/todos.rs"
click node_goals "https://github.com/alstes/todomate-cli/blob/main/src/commands/goals.rs"
click node_vision "https://github.com/alstes/todomate-cli/blob/main/src/commands/vision.rs"
click node_api "https://github.com/alstes/todomate-cli/blob/main/src/api/mod.rs"
click node_models "https://github.com/alstes/todomate-cli/blob/main/src/api/models.rs"
click node_auth "https://github.com/alstes/todomate-cli/blob/main/src/auth/mod.rs"
click node_gh_token "https://github.com/alstes/todomate-cli/blob/main/src/auth/gh_token.rs"
click node_device_flow "https://github.com/alstes/todomate-cli/blob/main/src/auth/device_flow.rs"
click node_output "https://github.com/alstes/todomate-cli/blob/main/src/output.rs"
click node_credentials "https://github.com/alstes/todomate-cli/blob/main/src/auth/token_store.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_parser,node_dispatcher,node_config,node_user toneBlue
class node_todos,node_goals,node_vision,node_credential_store toneAmber
class node_api,node_models,node_auth,node_gh_token,node_device_flow,node_todo_api toneMint
class node_output,node_credentials toneRose
class node_github_cli toneIndigo
```

## Components

### CLI entry and configuration

- [Command parser](https://github.com/alstes/todomate-cli/blob/main/src/cli.rs): `src/cli.rs`
- [Runtime dispatcher](https://github.com/alstes/todomate-cli/blob/main/src/main.rs): `src/main.rs`
- [Local configuration](https://github.com/alstes/todomate-cli/blob/main/src/config.rs): `src/config.rs`

### TodoMate domain commands

- [Todo commands](https://github.com/alstes/todomate-cli/blob/main/src/commands/todos.rs): `src/commands/todos.rs`
- [Goal commands](https://github.com/alstes/todomate-cli/blob/main/src/commands/goals.rs): `src/commands/goals.rs`
- [Vision commands](https://github.com/alstes/todomate-cli/blob/main/src/commands/vision.rs): `src/commands/vision.rs`

### API and authentication

- [API client](https://github.com/alstes/todomate-cli/blob/main/src/api/mod.rs): `src/api/mod.rs`
- [API data models](https://github.com/alstes/todomate-cli/blob/main/src/api/models.rs): `src/api/models.rs`
- [Authentication flow](https://github.com/alstes/todomate-cli/blob/main/src/auth/mod.rs): `src/auth/mod.rs`
- [GitHub token lookup](https://github.com/alstes/todomate-cli/blob/main/src/auth/gh_token.rs): `src/auth/gh_token.rs`
- [Device flow stub](https://github.com/alstes/todomate-cli/blob/main/src/auth/device_flow.rs): `src/auth/device_flow.rs`

### Output and local credentials

- [Text and JSON output](https://github.com/alstes/todomate-cli/blob/main/src/output.rs): `src/output.rs`
- [Credential storage](https://github.com/alstes/todomate-cli/blob/main/src/auth/token_store.rs): `src/auth/token_store.rs`

### Other components

- **Terminal user**
- **GitHub CLI**
- **TodoMate API**
- **OS keychain or file**

## Connections

- Terminal user → Command parser: enters commands (evidence: `README.md`)
- Command parser → Runtime dispatcher: parsed arguments (evidence: `src/main.rs`)
- Runtime dispatcher → Local configuration: loads or updates (evidence: `src/main.rs`)
- Runtime dispatcher → Authentication flow: routes auth (evidence: `src/main.rs`)
- Runtime dispatcher → Todo commands: routes todos (evidence: `src/main.rs`)
- Runtime dispatcher → Goal commands: routes goals (evidence: `src/main.rs`)
- Runtime dispatcher → Vision commands: routes vision (evidence: `src/main.rs`)
- Authentication flow → GitHub token lookup: gets token (evidence: `src/auth/mod.rs`)
- GitHub token lookup → GitHub CLI: reads token (evidence: `src/auth/gh_token.rs`)
- Authentication flow → API client: exchanges credentials (evidence: `src/auth/mod.rs`)
- Authentication flow → Credential storage: saves or checks (evidence: `src/auth/mod.rs`)
- Credential storage → OS keychain or file: persists credentials (evidence: `src/auth/token_store.rs`)
- API client → Credential storage: loads refresh credentials (evidence: `src/api/mod.rs`)
- Todo commands → API client: requests todo operations (evidence: `src/commands/todos.rs`)
- Goal commands → API client: requests goal operations (evidence: `src/commands/goals.rs`)
- Vision commands → API client: requests vision operations (evidence: `src/commands/vision.rs`)
- API client → TodoMate API: sends HTTP requests (evidence: `src/api/mod.rs`)
- API client → API data models: serializes and parses (evidence: `src/api/mod.rs`)
- Todo commands → Text and JSON output: formats results (evidence: `src/commands/todos.rs`)
- Goal commands → Text and JSON output: formats results (evidence: `src/commands/goals.rs`)
- Vision commands → Text and JSON output: formats results (evidence: `src/commands/vision.rs`)
- Text and JSON output → API data models: renders domain values (evidence: `src/output.rs`)
