How sxntaxis/strata works
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: app.rs App shell · render_views.rs Render views · cli.rs CLI · event_handlers.rs Events
Components 20
Entrypoints
Process entry, CLI dispatch, and top-level runtime selection.
Core model
Pure tracking rules and persistence boundaries.
- Domain rules · Categories, sessions, day boundaries, and report logic.
src/domain.rs - Storage · File-backed time log storage, atomic writes, and backups.
src/storage.rs
Terminal UI
Interactive app orchestration, views, input handling, and keymaps.
- App shell · Coordinates interactive state and delegates work to core layers.
src/app.rs - Events · Maps keyboard and UI events into app actions.
src/app/event_handlers.rs - Render views · Composes screen rendering from current state.
src/app/render_views.rs - UI helpers · Shared UI layout and drawing utilities.
src/app/ui_helpers.rs - Styles · Presentation styles and visual constants for the TUI.
src/app/view_style.rs - Keybindings · Action-to-key mapping and override loading.
src/keybindings.rs - Category state · State and coordination for category-focused modal flows.
src/app/category_state.rs - Report state · State and coordination for reporting flows.
src/app/report_state.rs - Category modal · Category editing and selection interface.
src/app/category_modal_view.rs - Report modal · Reporting UI and report-specific display.
src/app/report_modal_view.rs - Command palette · Global action launcher and command search.
src/app/command_palette_view.rs - Keymap modal · Interactive keybinding help and configuration view.
src/app/keybindings_modal_view.rs - Time format · 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 · Public surface for the sand simulation layer.
src/sand/mod.rs - Sand engine · Reconstructs and advances sand state from tracking history.
src/sand/engine.rs - Resize · Adjusts the simulation and rendering footprint on size changes.
src/sand/resize.rs
Connections 24
- 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.