# oughie/clock-rs architecture

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

- Interactive diagram: https://gitdiagram.com/oughie/clock-rs
- Repository: https://github.com/oughie/clock-rs

## Overview

clock-rs is a terminal digital clock with clock, timer, and stopwatch modes. Its workflow parses CLI options and configuration, selects a time or counter mode, then renders a formatted display in an interactive terminal loop; users can pause/restart counters and reload settings. Groups distinguish input/configuration, timekeeping, and presentation/runtime layers. The graph follows shown calls and README-described behavior; configuration-file details beyond the sampled parser are omitted.

Main entry points: [`src/state.rs`](https://github.com/oughie/clock-rs/blob/main/src/state.rs) (App state), [`src/clock/mod.rs`](https://github.com/oughie/clock-rs/blob/main/src/clock/mod.rs) (Clock formatter), [`src/clock/mode.rs`](https://github.com/oughie/clock-rs/blob/main/src/clock/mode.rs) (Clock modes), [`src/config.rs`](https://github.com/oughie/clock-rs/blob/main/src/config.rs) (Settings parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Inputs and configuration"]
  node_cli["CLI options<br/>[args.rs]"]
  node_config["Settings parser<br/>[config.rs]"]
  node_overrides["CLI overrides<br/>[mod.rs]"]
  node_configfile["TOML settings file"]
end

subgraph group_time["Time and counters"]
  node_clockmode["Clock modes<br/>[mode.rs]"]
  node_counter["Timer and stopwatch<br/>[counter.rs]"]
  node_timezone["Local and UTC time<br/>[time_zone.rs]"]
end

subgraph group_display["Terminal display"]
  node_clock["Clock formatter<br/>[mod.rs]"]
  node_character["Digit characters<br/>[character.rs]"]
  node_segments["Glyph segments<br/>[segment.rs]"]
  node_color["Color formatting<br/>[color.rs]"]
  node_position["Position layout<br/>[position.rs]"]
end

subgraph group_runtime["Application runtime"]
  node_state["App state<br/>[state.rs]"]
  node_mode["Mode selection<br/>[state.rs]"]
  node_terminal["Terminal I/O<br/>[state.rs]"]
  node_errors["Error reporting<br/>[error.rs]"]
end

node_user(("Terminal user"))

node_user -->|"starts app"| node_state
node_state -->|"parses options"| node_cli
node_state -->|"loads settings"| node_config
node_state -->|"applies overrides"| node_overrides
node_cli -->|"provides values"| node_overrides
node_configfile -->|"reads TOML"| node_config
node_state -->|"selects mode"| node_mode
node_mode -->|"constructs"| node_clockmode
node_mode -->|"creates counter"| node_counter
node_clockmode -.->|"gets time"| node_timezone
node_state -->|"configures display"| node_clock
node_clock -->|"formats mode"| node_clockmode
node_clock -->|"formats digits"| node_character
node_character -->|"formats glyph"| node_segments
node_clock -->|"applies color"| node_color
node_clock -->|"calculates layout"| node_position
node_state -->|"renders and polls"| node_terminal
node_terminal -->|"renders display"| node_clock
node_terminal -->|"pauses or restarts"| node_counter
node_terminal -->|"reloads settings"| node_config
node_state -->|"reports failures"| node_errors

click node_cli "https://github.com/oughie/clock-rs/blob/main/src/cli/args.rs"
click node_config "https://github.com/oughie/clock-rs/blob/main/src/config.rs"
click node_overrides "https://github.com/oughie/clock-rs/blob/main/src/cli/mod.rs"
click node_state "https://github.com/oughie/clock-rs/blob/main/src/state.rs"
click node_mode "https://github.com/oughie/clock-rs/blob/main/src/state.rs"
click node_clockmode "https://github.com/oughie/clock-rs/blob/main/src/clock/mode.rs"
click node_counter "https://github.com/oughie/clock-rs/blob/main/src/clock/counter.rs"
click node_timezone "https://github.com/oughie/clock-rs/blob/main/src/clock/time_zone.rs"
click node_clock "https://github.com/oughie/clock-rs/blob/main/src/clock/mod.rs"
click node_character "https://github.com/oughie/clock-rs/blob/main/src/character.rs"
click node_segments "https://github.com/oughie/clock-rs/blob/main/src/segment.rs"
click node_color "https://github.com/oughie/clock-rs/blob/main/src/color.rs"
click node_position "https://github.com/oughie/clock-rs/blob/main/src/position.rs"
click node_terminal "https://github.com/oughie/clock-rs/blob/main/src/state.rs"
click node_errors "https://github.com/oughie/clock-rs/blob/main/src/error.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_config,node_overrides,node_configfile,node_user toneBlue
class node_clockmode,node_counter,node_timezone toneAmber
class node_clock,node_character,node_segments,node_color,node_position toneMint
class node_state,node_mode,node_terminal,node_errors toneRose
```

## Components

### Inputs and configuration

- [CLI options](https://github.com/oughie/clock-rs/blob/main/src/cli/args.rs): `src/cli/args.rs`
- [Settings parser](https://github.com/oughie/clock-rs/blob/main/src/config.rs): `src/config.rs`
- [CLI overrides](https://github.com/oughie/clock-rs/blob/main/src/cli/mod.rs): `src/cli/mod.rs`
- **TOML settings file**

### Time and counters

- [Clock modes](https://github.com/oughie/clock-rs/blob/main/src/clock/mode.rs): `src/clock/mode.rs`
- [Timer and stopwatch](https://github.com/oughie/clock-rs/blob/main/src/clock/counter.rs): `src/clock/counter.rs`
- [Local and UTC time](https://github.com/oughie/clock-rs/blob/main/src/clock/time_zone.rs): `src/clock/time_zone.rs`

### Terminal display

- [Clock formatter](https://github.com/oughie/clock-rs/blob/main/src/clock/mod.rs): `src/clock/mod.rs`
- [Digit characters](https://github.com/oughie/clock-rs/blob/main/src/character.rs): `src/character.rs`
- [Glyph segments](https://github.com/oughie/clock-rs/blob/main/src/segment.rs): `src/segment.rs`
- [Color formatting](https://github.com/oughie/clock-rs/blob/main/src/color.rs): `src/color.rs`
- [Position layout](https://github.com/oughie/clock-rs/blob/main/src/position.rs): `src/position.rs`

### Application runtime

- [App state](https://github.com/oughie/clock-rs/blob/main/src/state.rs): `src/state.rs`
- [Mode selection](https://github.com/oughie/clock-rs/blob/main/src/state.rs): `src/state.rs`
- [Terminal I/O](https://github.com/oughie/clock-rs/blob/main/src/state.rs): `src/state.rs`
- [Error reporting](https://github.com/oughie/clock-rs/blob/main/src/error.rs): `src/error.rs`

### Other components

- **Terminal user**

## Connections

- Terminal user → App state: starts app
- App state → CLI options: parses options (evidence: `src/state.rs`)
- App state → Settings parser: loads settings (evidence: `src/state.rs`)
- App state → CLI overrides: applies overrides (evidence: `src/state.rs`)
- CLI options → CLI overrides: provides values (evidence: `src/cli/mod.rs`)
- TOML settings file → Settings parser: reads TOML (evidence: `src/config.rs`)
- App state → Mode selection: selects mode (evidence: `src/state.rs`)
- Mode selection → Clock modes: constructs (evidence: `src/state.rs`)
- Mode selection → Timer and stopwatch: creates counter (evidence: `src/state.rs`)
- Clock modes → Local and UTC time: gets time
- App state → Clock formatter: configures display (evidence: `src/state.rs`)
- Clock formatter → Clock modes: formats mode (evidence: `src/clock/mod.rs`)
- Clock formatter → Digit characters: formats digits (evidence: `src/clock/mod.rs`)
- Digit characters → Glyph segments: formats glyph (evidence: `src/character.rs`)
- Clock formatter → Color formatting: applies color (evidence: `src/clock/mod.rs`)
- Clock formatter → Position layout: calculates layout (evidence: `src/clock/mod.rs`)
- App state → Terminal I/O: renders and polls (evidence: `src/state.rs`)
- Terminal I/O → Clock formatter: renders display (evidence: `src/state.rs`)
- Terminal I/O → Timer and stopwatch: pauses or restarts (evidence: `src/state.rs`)
- Terminal I/O → Settings parser: reloads settings (evidence: `src/state.rs`)
- App state → Error reporting: reports failures (evidence: `src/main.rs`)
