# sxntaxis/strata architecture

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

- Interactive diagram: https://gitdiagram.com/sxntaxis/strata
- Repository: https://github.com/sxntaxis/strata

## Overview

1. **Repository shape**
   - Strata is a Rust application with two user-facing entry points: a terminal UI and a small CLI.
   - The code is organized around a clean split between **domain rules**, **persistent storage**, **TUI orchestration**, and a separate **sand simulation/rendering layer**.

2. **Top-level execution flow**
   - `src/main.rs` is the process entry.
   - It likely dispatches to either the interactive TUI path (`src/app.rs`) or the non-interactive CLI path (`src/cli.rs`) based on arguments.
   - Both paths ultimately operate on the same domain model and persisted time log data.

3. **Domain layer**
   - `src/domain.rs` contains the business logic: categories, sessions, day-boundary calculations, and report generation.
   - This layer is the source of truth for time-tracking behavior and should not depend on file I/O or UI concerns.
   - The README explicitly treats this as the boundary that must stay pure and stable.

4. **Storage layer**
   - `src/storage.rs` handles persistence, including CSV/JSON formats, filesystem paths, atomic writes, and backups.
   - Runtime data is stored under XDG locations, with an override via `STRATA_DATA_DIR`.
   - The storage layer bridges the domain model to files such as the time log and state artifacts, but does not render UI or implement business rules.

5. **TUI orchestration**
   - `src/app.rs` and `src/app/*` coordinate the terminal interface.
   - The app layer owns event handling, screen state, modal management, and render selection, but delegates all core decisions to the domain/storage boundaries.
   - Submodules like `category_state.rs`, `report_state.rs`, and the modal view files suggest the TUI is composed of focused view/state pairs rather than a monolithic screen.

6. **TUI rendering and interaction**
   - `render_views.rs`, `ui_helpers.rs`, and `view_style.rs` appear to centralize drawing logic, layout helpers, and styling.
   - `event_handlers.rs` translates keyboard input into actions.
   - `keybindings.rs` and the keybindings modal files indicate that actions are mapped through a configurable keymap, including optional overrides from `~/.config/strata/keymap.json`.

7. **CLI path**
   - `src/cli.rs` provides non-TUI command handling and output formatting.
   - The README example (`cargo run -- report --today`) implies this path is used for reporting and other scripted workflows.
   - The CLI likely reuses the same domain/report logic as the TUI, but skips interactive rendering entirely.

8. **Sand simulation subsystem**
   - `src/sand/engine.rs`, `src/sand/resize.rs`, and `src/sand/mod.rs` form a separate rendering/simulation engine used by the UI.
   - The README describes daily sand snapshots, drift filtering, and reconstructed historical snapshots, which means this subsystem is part of the visual representation of time-tracking history rather than the core business rules.
   - This is a distinct boundary: the UI consumes simulation state, but the domain still owns the underlying time data.

9. **Stateful UI features**
   - The presence of category, report, command-palette, and keybindings modal modules shows that the app has multiple overlay-style interaction modes.
   - `command_palette_view.rs` and `keybindings_modal_view.rs` suggest global actions are exposed through reusable modal components.
   - These are UI-only concerns layered on top of the core tracking model.

10. **Detached/catch-up behavior**
   - The README describes a detached mode where Strata can exit the TUI without ending tracking, then later reopen and catch up in the background.
   - That implies a runtime checkpoint in state storage, a replay queue for user actions, and a time-synced simulation loop.
   - Architecturally, this is an interaction between app state, storage-backed checkpoints, and the sand simulation cadence.

11. **Data flow across the system**
   - User input enters through the TUI keybinding/event layer.
   - The app layer converts it into actions, reads or updates domain state, and persists changes through storage.
   - Rendering is then derived from current app state plus domain data, with the sand engine providing the visual time/history presentation.
   - The CLI follows a simpler version of the same flow: command input → domain query/update → formatted output.

12. **Key architectural boundaries to preserve**
   - Domain stays free of filesystem and terminal dependencies.
   - Storage stays free of UI behavior.
   - The app layer orchestrates, but should avoid embedding business rules.
   - The sand subsystem remains a presentation/simulation concern, not a source of truth for time-tracking data.

Main entry points: [`src/app.rs`](https://github.com/sxntaxis/strata/blob/main/src/app.rs) (App shell), [`src/app/render_views.rs`](https://github.com/sxntaxis/strata/blob/main/src/app/render_views.rs) (Render views), [`src/cli.rs`](https://github.com/sxntaxis/strata/blob/main/src/cli.rs) (CLI), [`src/app/event_handlers.rs`](https://github.com/sxntaxis/strata/blob/main/src/app/event_handlers.rs) (Events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_main(("Main<br/>entrypoint<br/>[main.rs]"))
  node_cli["CLI<br/>command runner<br/>[cli.rs]"]
end

subgraph group_core["Core model"]
  node_domain{{"Domain rules<br/>pure model<br/>[domain.rs]"}}
  node_storage[("Storage<br/>persistence<br/>[storage.rs]")]
end

subgraph group_tui["Terminal UI"]
  node_app["App shell<br/>tui orchestrator<br/>[app.rs]"]
  node_events["Events<br/>input routing<br/>[event_handlers.rs]"]
  node_views["Render views<br/>view renderer<br/>[render_views.rs]"]
  node_helpers["UI helpers<br/>layout helpers<br/>[ui_helpers.rs]"]
  node_styles["Styles<br/>theme<br/>[view_style.rs]"]
  node_kb["Keybindings<br/>keymap<br/>[keybindings.rs]"]
  node_cat_state["Category state<br/>screen state<br/>[category_state.rs]"]
  node_report_state["Report state<br/>screen state<br/>[report_state.rs]"]
  node_cat_modal["Category modal<br/>modal view"]
  node_report_modal["Report modal<br/>modal view"]
  node_palette["Command palette<br/>modal view"]
  node_kb_modal["Keymap modal<br/>modal view"]
  node_timefmt["Time format<br/>formatting<br/>[time_format.rs]"]
end

subgraph group_sand["Sand system"]
  node_sand_mod["Sand mod<br/>simulation facade<br/>[mod.rs]"]
  node_engine["Sand engine<br/>simulation<br/>[engine.rs]"]
  node_resize["Resize<br/>viewport handling<br/>[resize.rs]"]
end

node_main -->|"dispatch"| node_cli
node_main -->|"dispatch"| node_app
node_cli -->|"queries"| node_domain
node_cli -->|"loads/saves"| node_storage
node_app -->|"routes input"| node_events
node_app -->|"renders"| node_views
node_app -->|"resolves keys"| node_kb
node_app -->|"applies rules"| node_domain
node_app -->|"persists"| node_storage
node_app -->|"drives visuals"| node_sand_mod
node_events -->|"updates"| node_cat_state
node_events -->|"updates"| node_report_state
node_cat_state -->|"shows"| node_cat_modal
node_report_state -->|"shows"| node_report_modal
node_app -->|"opens"| node_palette
node_app -->|"opens"| node_kb_modal
node_views -->|"uses"| node_helpers
node_views -->|"uses"| node_styles
node_views -->|"formats"| node_timefmt
node_sand_mod -->|"contains"| node_engine
node_sand_mod -->|"handles"| node_resize
node_engine -->|"replays"| node_storage
node_engine -->|"consumes"| node_domain
node_app -->|"shares"| node_timefmt

click node_main "https://github.com/sxntaxis/strata/blob/main/src/main.rs"
click node_cli "https://github.com/sxntaxis/strata/blob/main/src/cli.rs"
click node_app "https://github.com/sxntaxis/strata/blob/main/src/app.rs"
click node_events "https://github.com/sxntaxis/strata/blob/main/src/app/event_handlers.rs"
click node_views "https://github.com/sxntaxis/strata/blob/main/src/app/render_views.rs"
click node_helpers "https://github.com/sxntaxis/strata/blob/main/src/app/ui_helpers.rs"
click node_styles "https://github.com/sxntaxis/strata/blob/main/src/app/view_style.rs"
click node_kb "https://github.com/sxntaxis/strata/blob/main/src/keybindings.rs"
click node_cat_state "https://github.com/sxntaxis/strata/blob/main/src/app/category_state.rs"
click node_report_state "https://github.com/sxntaxis/strata/blob/main/src/app/report_state.rs"
click node_cat_modal "https://github.com/sxntaxis/strata/blob/main/src/app/category_modal_view.rs"
click node_report_modal "https://github.com/sxntaxis/strata/blob/main/src/app/report_modal_view.rs"
click node_palette "https://github.com/sxntaxis/strata/blob/main/src/app/command_palette_view.rs"
click node_kb_modal "https://github.com/sxntaxis/strata/blob/main/src/app/keybindings_modal_view.rs"
click node_timefmt "https://github.com/sxntaxis/strata/blob/main/src/app/time_format.rs"
click node_domain "https://github.com/sxntaxis/strata/blob/main/src/domain.rs"
click node_storage "https://github.com/sxntaxis/strata/blob/main/src/storage.rs"
click node_sand_mod "https://github.com/sxntaxis/strata/blob/main/src/sand/mod.rs"
click node_engine "https://github.com/sxntaxis/strata/blob/main/src/sand/engine.rs"
click node_resize "https://github.com/sxntaxis/strata/blob/main/src/sand/resize.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_main,node_cli toneBlue
class node_domain,node_storage toneAmber
class node_app,node_events,node_views,node_helpers,node_styles,node_kb,node_cat_state,node_report_state,node_cat_modal,node_report_modal,node_palette,node_kb_modal,node_timefmt toneMint
class node_sand_mod,node_engine,node_resize toneRose
```

## Components

### Entrypoints

Process entry, CLI dispatch, and top-level runtime selection.

- [Main](https://github.com/sxntaxis/strata/blob/main/src/main.rs): entrypoint · Process start and runtime dispatch. · `src/main.rs`
- [CLI](https://github.com/sxntaxis/strata/blob/main/src/cli.rs): command runner · Non-interactive commands and formatted output. · `src/cli.rs`

### Core model

Pure tracking rules and persistence boundaries.

- [Domain rules](https://github.com/sxntaxis/strata/blob/main/src/domain.rs): pure model · Categories, sessions, day boundaries, and report logic. · `src/domain.rs`
- [Storage](https://github.com/sxntaxis/strata/blob/main/src/storage.rs): persistence · File-backed time log storage, atomic writes, and backups. · `src/storage.rs`

### Terminal UI

Interactive app orchestration, views, input handling, and keymaps.

- [App shell](https://github.com/sxntaxis/strata/blob/main/src/app.rs): tui orchestrator · Coordinates interactive state and delegates work to core layers. · `src/app.rs`
- [Events](https://github.com/sxntaxis/strata/blob/main/src/app/event_handlers.rs): input routing · Maps keyboard and UI events into app actions. · `src/app/event_handlers.rs`
- [Render views](https://github.com/sxntaxis/strata/blob/main/src/app/render_views.rs): view renderer · Composes screen rendering from current state. · `src/app/render_views.rs`
- [UI helpers](https://github.com/sxntaxis/strata/blob/main/src/app/ui_helpers.rs): layout helpers · Shared UI layout and drawing utilities. · `src/app/ui_helpers.rs`
- [Styles](https://github.com/sxntaxis/strata/blob/main/src/app/view_style.rs): theme · Presentation styles and visual constants for the TUI. · `src/app/view_style.rs`
- [Keybindings](https://github.com/sxntaxis/strata/blob/main/src/keybindings.rs): keymap · Action-to-key mapping and override loading. · `src/keybindings.rs`
- [Category state](https://github.com/sxntaxis/strata/blob/main/src/app/category_state.rs): screen state · State and coordination for category-focused modal flows. · `src/app/category_state.rs`
- [Report state](https://github.com/sxntaxis/strata/blob/main/src/app/report_state.rs): screen state · State and coordination for reporting flows. · `src/app/report_state.rs`
- [Category modal](https://github.com/sxntaxis/strata/blob/main/src/app/category_modal_view.rs): modal view · Category editing and selection interface. · `src/app/category_modal_view.rs`
- [Report modal](https://github.com/sxntaxis/strata/blob/main/src/app/report_modal_view.rs): modal view · Reporting UI and report-specific display. · `src/app/report_modal_view.rs`
- [Command palette](https://github.com/sxntaxis/strata/blob/main/src/app/command_palette_view.rs): modal view · Global action launcher and command search. · `src/app/command_palette_view.rs`
- [Keymap modal](https://github.com/sxntaxis/strata/blob/main/src/app/keybindings_modal_view.rs): modal view · Interactive keybinding help and configuration view. · `src/app/keybindings_modal_view.rs`
- [Time format](https://github.com/sxntaxis/strata/blob/main/src/app/time_format.rs): formatting · Shared time display and parsing helpers. · `src/app/time_format.rs`

### Sand system

Visual simulation layer used by the UI for history and motion.

- [Sand mod](https://github.com/sxntaxis/strata/blob/main/src/sand/mod.rs): simulation facade · Public surface for the sand simulation layer. · `src/sand/mod.rs`
- [Sand engine](https://github.com/sxntaxis/strata/blob/main/src/sand/engine.rs): simulation · Reconstructs and advances sand state from tracking history. · `src/sand/engine.rs`
- [Resize](https://github.com/sxntaxis/strata/blob/main/src/sand/resize.rs): viewport handling · Adjusts the simulation and rendering footprint on size changes. · `src/sand/resize.rs`

## Connections

- Main → CLI: dispatch · Selects the non-interactive command path when needed.
- Main → App shell: dispatch · Starts the interactive terminal application.
- CLI → Domain rules: queries · Uses domain logic for reports and tracked-time operations.
- CLI → Storage: loads/saves · Reads and persists time-log data for scripted commands.
- App shell → Events: routes input · Converts UI events into application actions.
- App shell → Render views: renders · Builds the active terminal screen from state.
- App shell → Keybindings: resolves keys · Uses keybindings to interpret input and expose actions.
- App shell → Domain rules: applies rules · Delegates tracking and reporting decisions to the pure model.
- App shell → Storage: persists · Reads and writes runtime state through the persistence layer.
- App shell → Sand mod: drives visuals · Feeds time/history state into the sand presentation layer.
- Events → Category state: updates · Drives category interaction state.
- Events → Report state: updates · Drives report interaction state.
- Category state → Category modal: shows · Owns the category modal flow and its view state.
- Report state → Report modal: shows · Owns the report modal flow and its view state.
- App shell → Command palette: opens · Exposes global commands through the command palette.
- App shell → Keymap modal: opens · Shows keybinding help and overrides.
- Render views → UI helpers: uses · Relies on shared layout and drawing helpers.
- Render views → Styles: uses · Applies theme and styling definitions.
- Render views → Time format: formats · Shares time display logic across screens.
- Sand mod → Sand engine: contains · Public simulation API backed by the core engine.
- Sand mod → Resize: handles · Adapts the simulation to terminal size changes.
- Sand engine → Storage: replays · Reconstructs historical state from persisted logs.
- Sand engine → Domain rules: consumes · Uses domain time data as the source of truth.
- App shell → Time format: shares · Uses common time formatting in interactive flows.
