trasta298/keifu

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.