# itsjustayush/beton-cli architecture

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

- Interactive diagram: https://gitdiagram.com/itsjustayush/beton-cli
- Repository: https://github.com/itsjustayush/beton-cli

## Overview

BETON is a local-first command-line layer for everyday computer actions. Users invoke the Python CLI, which dispatches commands such as open, search, note, timer, and system control to focused domain modules; results are rendered in the terminal. Configuration and notes remain local, while opening targets delegates to platform adapters and search constructs a URL before the CLI opens it. The README documents additional capabilities whose handlers were not fully excerpted, so those links are shown as unverified. The npm runtime wrapper is included as a documented alternate entry point.

Main entry points: [`src/beton/cli.py`](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/cli.py) (Command dispatcher), [`src/beton/config.py`](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/config.py) (Settings service), [`src/beton/storage/notes.py`](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/storage/notes.py) (Notes service), [`src/beton/platform/base.py`](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/platform/base.py) (Platform adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry"]
  node_cli["Command dispatcher<br/>[cli.py]"]
  node_npm["npm runtime wrapper<br/>[beton.js]"]
end

subgraph group_actions["Local actions"]
  node_search["Search URL builder<br/>[search.py]"]
  node_resolver["Target resolver<br/>[resolver.py]"]
  node_notes["Notes service<br/>[notes.py]"]
  node_timer["Countdown timer<br/>[timer.py]"]
  node_system["System controls<br/>[system.py]"]
  node_upgrade["Upgrade service<br/>[upgrade.py]"]
  node_renderer["Terminal renderer<br/>[output.py]"]
end

subgraph group_platform["Platform services"]
  node_adapter["Platform adapter<br/>[base.py]"]
  node_adapter_select["Adapter selection<br/>[__init__.py]"]
end

subgraph group_state["Local state"]
  node_config["Settings service<br/>[config.py]"]
  node_settings[("Local settings file<br/>[config.py]")]
  node_note_file[("Markdown notes<br/>[notes.py]")]
end

node_user(("CLI user"))
node_host["Host operating system"]
node_browser["Web browser"]

node_user -->|"runs commands"| node_cli
node_npm -.->|"launches runtime"| node_cli
node_cli -->|"builds search URL"| node_search
node_cli -->|"resolves target"| node_resolver
node_cli -->|"gets adapter"| node_adapter_select
node_cli -.->|"handles note commands"| node_notes
node_cli -.->|"runs countdown"| node_timer
node_cli -.->|"handles system actions"| node_system
node_cli -->|"requests upgrade"| node_upgrade
node_cli -.->|"manages settings"| node_config
node_cli -->|"renders results"| node_renderer
node_search -->|"returns URL"| node_cli
node_resolver -->|"reads aliases"| node_config
node_adapter_select -->|"selects implementation"| node_adapter
node_adapter -->|"launches targets"| node_host
node_adapter -->|"opens URLs"| node_browser
node_notes -->|"gets note path"| node_config
node_notes -->|"reads and appends"| node_note_file
node_config -->|"reads and writes"| node_settings

click node_cli "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/cli.py"
click node_npm "https://github.com/itsjustayush/beton-cli/blob/main/npm-package/bin/beton.js"
click node_search "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/search.py"
click node_resolver "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/resolver.py"
click node_notes "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/storage/notes.py"
click node_timer "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/timer.py"
click node_system "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/system.py"
click node_upgrade "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/upgrade.py"
click node_renderer "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/output.py"
click node_config "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/config.py"
click node_settings "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/config.py"
click node_note_file "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/storage/notes.py"
click node_adapter "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/platform/base.py"
click node_adapter_select "https://github.com/itsjustayush/beton-cli/blob/main/src/beton/platform/__init__.py"

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_npm,node_user,node_browser toneBlue
class node_search,node_resolver,node_notes,node_timer,node_system,node_upgrade,node_renderer toneAmber
class node_adapter,node_adapter_select toneMint
class node_config,node_settings,node_note_file toneRose
class node_host toneIndigo
```

## Components

### Command entry

- [Command dispatcher](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/cli.py): `src/beton/cli.py`
- [npm runtime wrapper](https://github.com/itsjustayush/beton-cli/blob/main/npm-package/bin/beton.js): `npm-package/bin/beton.js`

### Local actions

- [Search URL builder](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/search.py): `src/beton/search.py`
- [Target resolver](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/resolver.py): `src/beton/resolver.py`
- [Notes service](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/storage/notes.py): `src/beton/storage/notes.py`
- [Countdown timer](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/timer.py): `src/beton/timer.py`
- [System controls](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/system.py): `src/beton/system.py`
- [Upgrade service](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/upgrade.py): `src/beton/upgrade.py`
- [Terminal renderer](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/output.py): `src/beton/output.py`

### Platform services

- [Platform adapter](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/platform/base.py): `src/beton/platform/base.py`
- [Adapter selection](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/platform/__init__.py): `src/beton/platform/__init__.py`

### Local state

- [Settings service](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/config.py): `src/beton/config.py`
- [Local settings file](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/config.py): `src/beton/config.py`
- [Markdown notes](https://github.com/itsjustayush/beton-cli/blob/main/src/beton/storage/notes.py): `src/beton/storage/notes.py`

### Other components

- **CLI user**
- **Host operating system**
- **Web browser**

## Connections

- CLI user → Command dispatcher: runs commands (evidence: `README.md`)
- npm runtime wrapper → Command dispatcher: launches runtime (evidence: `README.md`)
- Command dispatcher → Search URL builder: builds search URL (evidence: `src/beton/cli.py`)
- Command dispatcher → Target resolver: resolves target (evidence: `src/beton/cli.py`)
- Command dispatcher → Adapter selection: gets adapter (evidence: `src/beton/cli.py`)
- Command dispatcher → Notes service: handles note commands (evidence: `src/beton/cli.py`)
- Command dispatcher → Countdown timer: runs countdown (evidence: `src/beton/cli.py`)
- Command dispatcher → System controls: handles system actions (evidence: `src/beton/cli.py`)
- Command dispatcher → Upgrade service: requests upgrade (evidence: `src/beton/cli.py`)
- Command dispatcher → Settings service: manages settings (evidence: `src/beton/cli.py`)
- Command dispatcher → Terminal renderer: renders results (evidence: `src/beton/cli.py`)
- Search URL builder → Command dispatcher: returns URL (evidence: `src/beton/cli.py`)
- Target resolver → Settings service: reads aliases (evidence: `src/beton/resolver.py`)
- Adapter selection → Platform adapter: selects implementation (evidence: `src/beton/platform/__init__.py`)
- Platform adapter → Host operating system: launches targets (evidence: `src/beton/platform/base.py`)
- Platform adapter → Web browser: opens URLs (evidence: `src/beton/platform/base.py`)
- Notes service → Settings service: gets note path (evidence: `src/beton/storage/notes.py`)
- Notes service → Markdown notes: reads and appends (evidence: `src/beton/storage/notes.py`)
- Settings service → Local settings file: reads and writes (evidence: `src/beton/config.py`)
