# trasta298/keifu architecture

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

- Interactive diagram: https://gitdiagram.com/trasta298/keifu
- Repository: https://github.com/trasta298/keifu

## Overview

1. **What this repository is**
   - `keifu` is a Rust terminal UI for browsing Git history, not a general Git client.
   - The core product boundary is: read repository state, build a commit/branch graph, render it in the terminal, and allow a small set of branch operations.

2. **Top-level runtime flow**
   - `main.rs` bootstraps the app, `tui.rs` owns terminal setup/teardown, and `app.rs` drives the event loop.
   - User input comes in through `event.rs`, is translated by `action.rs` and `keybindings.rs`, then applied to app state.
   - State changes trigger re-rendering of the TUI and, when needed, reloads from the Git repository.

3. **Git access boundary**
   - Everything repository-related is isolated under `src/git/`.
   - That layer is responsible for discovering the repo, reading branches/commits/diffs, and performing operations like checkout, branch create/delete, and fetch.
   - The README indicates `git` in PATH is required for fetch, so the app relies on local Git state and system Git for at least some operations.

4. **Repository data model**
   - `repository.rs`, `branch.rs`, `commit.rs`, `diff.rs`, `operations.rs`, and `extensions.rs` suggest a domain model for Git objects plus helper logic.
   - This layer is the source of truth for:
     - commit metadata
     - branch labels and HEAD positioning
     - file-change summaries
     - working tree state, including uncommitted changes
   - The app caps history at 500 commits and changed files at 50, so the repository layer likely pre-filters data for UI use.

5. **Graph construction and layout**
   - `src/graph/` is the dedicated visualization subsystem.
   - `graph.rs` and `colors.rs` likely turn commits/branches into a drawable graph with per-branch coloring and lane management.
   - This is the boundary between Git semantics and screen rendering: it converts history into a compact visual representation suitable for narrow terminals.

6. **Primary screen composition**
   - `src/ui/graph_view.rs` is the main commit browser panel.
   - `commit_detail.rs` shows the selected commit’s full message and file stats.
   - `status_bar.rs` communicates mode, selection, and hints.
   - The main screen therefore combines graph, metadata, and selection context into one split-pane layout.

7. **Secondary interaction views**
   - `file_diff_view.rs` is a focused diff browser with scrolling and hunk/file navigation.
   - `search_dropdown.rs` provides branch search with incremental fuzzy selection.
   - `dialog.rs` handles confirmation-style prompts, while `help_popup.rs` provides keybinding help.
   - These are modal overlays rather than separate application screens, which keeps the main graph view as the central workspace.

8. **Search and navigation**
   - `search.rs` appears to implement branch search and result ranking.
   - Combined with `keybindings.rs`, the app supports keyboard-driven navigation across commits, branches, and search results.
   - Special jump keys like next/previous labeled commit and HEAD navigation indicate the app is optimized for graph traversal rather than linear log browsing.

9. **Git operations as actions**
   - `action.rs` likely maps user commands to concrete repository mutations or view transitions.
   - Supported operations are intentionally limited: checkout, create branch, delete local branch, and fetch.
   - This keeps the app closer to a visual Git navigation tool than a full editing environment.

10. **Configuration and adaptability**
   - `config.rs` and `docs/configuration.md` indicate user-configurable behavior.
   - The README also notes narrow-terminal support, conditional field hiding, and colorized Unicode rendering, so UI layout adapts to terminal constraints.
   - This matters architecturally because rendering decisions depend on terminal width and available space.

11. **Testing boundaries**
   - `tests/graph_test.rs` validates graph behavior, and `tests/untracked_working_tree_test.rs` covers repository state with untracked changes.
   - That split shows the project tests both the visualization logic and the Git-state edge cases that affect what the UI displays.

12. **Build and release workflow**
   - The repository includes GitHub Actions for CI and release plus `cliff.toml` for changelog/release automation.
   - These are peripheral to runtime architecture, but they show the project is packaged as a Rust CLI/TUI binary with automated publishing.

13. **How to draw the architecture**
   - A good diagram would show:
     - terminal input/output at the edges
     - the app/event loop in the center
     - a Git repository subsystem feeding commit/branch/diff data
     - a graph/layout subsystem transforming that data into lanes/colors
     - UI modules consuming the rendered model and presenting main/detail/modal views
   - The key architectural boundary is between Git-domain data acquisition and TUI presentation; everything else supports that split.

Main entry points: [`src/app.rs`](https://github.com/trasta298/keifu/blob/main/src/app.rs) (App loop), [`src/git/repository.rs`](https://github.com/trasta298/keifu/blob/main/src/git/repository.rs) (Repository), [`src/action.rs`](https://github.com/trasta298/keifu/blob/main/src/action.rs) (Actions), [`src/ui/graph_view.rs`](https://github.com/trasta298/keifu/blob/main/src/ui/graph_view.rs) (Graph view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("Main<br/>entrypoint<br/>[main.rs]"))
  node_tui["TUI<br/>terminal shell<br/>[tui.rs]"]
  node_app["App loop<br/>state loop<br/>[app.rs]"]
  node_event["Events<br/>input pump<br/>[event.rs]"]
  node_action["Actions<br/>command map<br/>[action.rs]"]
end

subgraph group_git["Git Domain"]
  node_repository[("Repository<br/>git state<br/>[repository.rs]")]
  node_branch["Branches<br/>branch model<br/>[branch.rs]"]
  node_commit["Commits<br/>commit model<br/>[commit.rs]"]
  node_diff["Diffs<br/>change model<br/>[diff.rs]"]
  node_operations["Ops<br/>git actions<br/>[operations.rs]"]
  node_git_graph["Git graph<br/>git adapter<br/>[graph.rs]"]
end

subgraph group_viz["Graph"]
  node_graph["Layout<br/>[mod.rs]"]
  node_colors["Colors<br/>render palette<br/>[colors.rs]"]
end

subgraph group_ui["UI"]
  node_graph_view["Graph view<br/>main panel<br/>[graph_view.rs]"]
  node_commit_detail["Commit detail<br/>detail pane<br/>[commit_detail.rs]"]
  node_status_bar["Status bar<br/>hud<br/>[status_bar.rs]"]
  node_file_diff_view["Diff view<br/>modal panel<br/>[file_diff_view.rs]"]
  node_search_dropdown["Search<br/>picker<br/>[search_dropdown.rs]"]
  node_dialog["Dialog<br/>confirm modal<br/>[dialog.rs]"]
  node_help_popup["Help<br/>overlay<br/>[help_popup.rs]"]
end

subgraph group_support["Support"]
  node_keybindings["Keybinds<br/>binding map<br/>[keybindings.rs]"]
  node_config["Config<br/>settings<br/>[config.rs]"]
  node_search["Search logic<br/>ranking<br/>[search.rs]"]
end

node_main -->|"boot"| node_tui
node_main -->|"run"| node_app
node_app -->|"read"| node_event
node_app -->|"dispatch"| node_action
node_action -->|"resolve"| node_keybindings
node_action -->|"query"| node_repository
node_action -->|"mutate"| node_operations
node_app -->|"render"| node_graph_view
node_app -->|"render"| node_commit_detail
node_app -->|"render"| node_status_bar
node_app -->|"overlay"| node_file_diff_view
node_app -->|"overlay"| node_search_dropdown
node_app -->|"overlay"| node_dialog
node_app -->|"overlay"| node_help_popup
node_repository -->|"load"| node_branch
node_repository -->|"load"| node_commit
node_repository -->|"load"| node_diff
node_repository -->|"feed"| node_git_graph
node_git_graph -->|"layout"| node_graph
node_graph -->|"color"| node_colors
node_graph_view -->|"consume"| node_graph
node_graph_view -->|"inspect"| node_commit
node_commit_detail -->|"inspect"| node_commit
node_commit_detail -->|"inspect"| node_diff
node_search_dropdown -->|"rank"| node_search
node_search_dropdown -->|"suggest"| node_branch
node_config -->|"layout"| node_graph_view
node_config -->|"toggle"| node_help_popup

click node_main "https://github.com/trasta298/keifu/blob/main/src/main.rs"
click node_tui "https://github.com/trasta298/keifu/blob/main/src/tui.rs"
click node_app "https://github.com/trasta298/keifu/blob/main/src/app.rs"
click node_event "https://github.com/trasta298/keifu/blob/main/src/event.rs"
click node_action "https://github.com/trasta298/keifu/blob/main/src/action.rs"
click node_keybindings "https://github.com/trasta298/keifu/blob/main/src/keybindings.rs"
click node_config "https://github.com/trasta298/keifu/blob/main/src/config.rs"
click node_repository "https://github.com/trasta298/keifu/blob/main/src/git/repository.rs"
click node_branch "https://github.com/trasta298/keifu/blob/main/src/git/branch.rs"
click node_commit "https://github.com/trasta298/keifu/blob/main/src/git/commit.rs"
click node_diff "https://github.com/trasta298/keifu/blob/main/src/git/diff.rs"
click node_operations "https://github.com/trasta298/keifu/blob/main/src/git/operations.rs"
click node_git_graph "https://github.com/trasta298/keifu/blob/main/src/git/graph.rs"
click node_graph "https://github.com/trasta298/keifu/blob/main/src/graph/mod.rs"
click node_colors "https://github.com/trasta298/keifu/blob/main/src/graph/colors.rs"
click node_graph_view "https://github.com/trasta298/keifu/blob/main/src/ui/graph_view.rs"
click node_commit_detail "https://github.com/trasta298/keifu/blob/main/src/ui/commit_detail.rs"
click node_status_bar "https://github.com/trasta298/keifu/blob/main/src/ui/status_bar.rs"
click node_file_diff_view "https://github.com/trasta298/keifu/blob/main/src/ui/file_diff_view.rs"
click node_search_dropdown "https://github.com/trasta298/keifu/blob/main/src/ui/search_dropdown.rs"
click node_dialog "https://github.com/trasta298/keifu/blob/main/src/ui/dialog.rs"
click node_help_popup "https://github.com/trasta298/keifu/blob/main/src/ui/help_popup.rs"
click node_search "https://github.com/trasta298/keifu/blob/main/src/search.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_tui,node_app,node_event,node_action toneBlue
class node_repository,node_branch,node_commit,node_diff,node_operations,node_git_graph toneAmber
class node_graph,node_colors toneMint
class node_graph_view,node_commit_detail,node_status_bar,node_file_diff_view,node_search_dropdown,node_dialog,node_help_popup toneRose
class node_keybindings,node_config,node_search toneIndigo
```

## Components

### Runtime

Terminal bootstrap, event loop, and command dispatch

- [Main](https://github.com/trasta298/keifu/blob/main/src/main.rs): entrypoint · Starts the application and wires top-level runtime pieces · `src/main.rs`
- [TUI](https://github.com/trasta298/keifu/blob/main/src/tui.rs): terminal shell · Owns terminal setup and teardown · `src/tui.rs`
- [App loop](https://github.com/trasta298/keifu/blob/main/src/app.rs): state loop · Drives the event loop and screen updates · `src/app.rs`
- [Events](https://github.com/trasta298/keifu/blob/main/src/event.rs): input pump · Reads keyboard and terminal events · `src/event.rs`
- [Actions](https://github.com/trasta298/keifu/blob/main/src/action.rs): command map · Translates input into app commands and view changes · `src/action.rs`

### Git Domain

Repository discovery, history data, and branch operations

- [Repository](https://github.com/trasta298/keifu/blob/main/src/git/repository.rs): git state · Discovers the repo and serves repository state · `src/git/repository.rs`
- [Branches](https://github.com/trasta298/keifu/blob/main/src/git/branch.rs): branch model · Branch labels, HEAD placement, and branch state · `src/git/branch.rs`
- [Commits](https://github.com/trasta298/keifu/blob/main/src/git/commit.rs): commit model · Commit metadata and history records · `src/git/commit.rs`
- [Diffs](https://github.com/trasta298/keifu/blob/main/src/git/diff.rs): change model · File-change summaries and working tree changes · `src/git/diff.rs`
- [Ops](https://github.com/trasta298/keifu/blob/main/src/git/operations.rs): git actions · Checkout, branch create/delete, and fetch operations · `src/git/operations.rs`
- [Git graph](https://github.com/trasta298/keifu/blob/main/src/git/graph.rs): git adapter · Transforms repository history into graph-friendly data · `src/git/graph.rs`

### Graph

History graph construction and coloring

- [Layout](https://github.com/trasta298/keifu/blob/main/src/graph/mod.rs): lane layout · Builds commit lanes and visual structure · `src/graph/mod.rs`
- [Colors](https://github.com/trasta298/keifu/blob/main/src/graph/colors.rs): render palette · Assigns per-branch coloring for the history graph · `src/graph/colors.rs`

### UI

Main view and overlays

- [Graph view](https://github.com/trasta298/keifu/blob/main/src/ui/graph_view.rs): main panel · Primary commit browser and history pane · `src/ui/graph_view.rs`
- [Commit detail](https://github.com/trasta298/keifu/blob/main/src/ui/commit_detail.rs): detail pane · Shows selected commit message and file stats · `src/ui/commit_detail.rs`
- [Status bar](https://github.com/trasta298/keifu/blob/main/src/ui/status_bar.rs): hud · Displays mode, selection, and hints · `src/ui/status_bar.rs`
- [Diff view](https://github.com/trasta298/keifu/blob/main/src/ui/file_diff_view.rs): modal panel · Scrollable file and hunk diff browser · `src/ui/file_diff_view.rs`
- [Search](https://github.com/trasta298/keifu/blob/main/src/ui/search_dropdown.rs): picker · Incremental branch search and selection · `src/ui/search_dropdown.rs`
- [Dialog](https://github.com/trasta298/keifu/blob/main/src/ui/dialog.rs): confirm modal · Confirmation and prompt overlays · `src/ui/dialog.rs`
- [Help](https://github.com/trasta298/keifu/blob/main/src/ui/help_popup.rs): overlay · Shows keybinding help and shortcuts · `src/ui/help_popup.rs`

### Support

Configuration and input mapping

- [Keybinds](https://github.com/trasta298/keifu/blob/main/src/keybindings.rs): binding map · Defines keyboard shortcuts and navigation keys · `src/keybindings.rs`
- [Config](https://github.com/trasta298/keifu/blob/main/src/config.rs): settings · Loads user-facing behavior and layout preferences · `src/config.rs`
- [Search logic](https://github.com/trasta298/keifu/blob/main/src/search.rs): ranking · Ranks and filters branch search results · `src/search.rs`

## Connections

- Main → TUI: boot · Initializes terminal mode and screen lifecycle
- Main → App loop: run · Starts the application loop
- App loop → Events: read · Consumes user input and terminal events
- App loop → Actions: dispatch · Turns inputs into application actions
- Actions → Keybinds: resolve · Maps keys to commands and navigation
- Actions → Repository: query · Requests repository state for refresh and navigation
- Actions → Ops: mutate · Triggers checkout, branch, and fetch operations
- App loop → Graph view: render · Drives the main history browser
- App loop → Commit detail: render · Updates selected commit details
- App loop → Status bar: render · Updates mode and hint display
- App loop → Diff view: overlay · Opens diff-focused browsing when requested
- App loop → Search: overlay · Opens branch search UI
- App loop → Dialog: overlay · Shows confirmation prompts
- App loop → Help: overlay · Shows keybinding help
- Repository → Branches: load · Provides branch labels and HEAD state
- Repository → Commits: load · Provides commit history and metadata
- Repository → Diffs: load · Provides file changes and working tree state
- Repository → Git graph: feed · Supplies history data for graph construction
- Git graph → Layout: layout · Converts Git history into drawable lanes
- Layout → Colors: color · Applies branch coloring to lanes and nodes
- Graph view → Layout: consume · Displays the rendered history model
- Graph view → Commits: inspect · Uses commit metadata for the selected row
- Commit detail → Commits: inspect · Shows full commit information
- Commit detail → Diffs: inspect · Shows file statistics and change summaries
- Search → Search logic: rank · Filters and orders branch matches
- Search → Branches: suggest · Searches branch names for selection
- Config → Graph view: layout · Affects density, visibility, and terminal adaptation
- Config → Help: toggle · Influences what help and UI hints are shown