# faldor20/jj_tui architecture

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

- Interactive diagram: https://gitdiagram.com/faldor20/jj_tui
- Repository: https://github.com/faldor20/jj_tui

## Overview

##### Main Components
- Main Application (jj_tui):
– Entry point is found in the “jj_tui/bin” directory (e.g., main.ml).
– This core module manages the UI loop, command dispatch, and overall application flow.
- Command Modules:
– There are two primary command systems: one for “graph commands” (located in jj_tui/bin/graph_commands.ml) and another for “file commands” (jj_tui/bin/file_commands.ml).
– These modules interpret user input and dispatch appropriate actions.
- UI and Rendering Modules:
– In addition, the project includes forks of “nottui” and “notty” which are likely used or extended to handle terminal UI rendering and interactions.
- Configuration and Key Mapping:
– The configuration modules (located in jj_tui/lib/config.ml and jj_tui/lib/key_map.ml) provide customizable key commands via an external YAML configuration.
- External Dependency – Jujutsu CLI:
– The README emphasizes that the proper operation of jj_tui relies on the external jujutsu version control system CLI.
- Build & Dev Infrastructure:
– The presence of dune files, flake.nix, and GitHub workflows (.github/workflows) show that the project uses both dune (OCaml’s build system) and nix for reproducible development environments.

##### Relationships and Interactions
- User and Terminal Interaction Flow:
– The user interacts with the terminal, whereby key presses are captured and processed by the TUI’s key event handlers.
– The key events are then mapped (via the key_map module) to specific commands.
- Command Processing Layer:
– Depending on whether the TUI is in “graph” or “files” mode, input is routed to the corresponding command modules.
– These modules then determine if a command affects the UI or requires invoking actions using the jujutsu CLI.
- UI Rendering and Updates:
– The UI (built with widgets provided by both internal libraries and forks of notty/nottui) is updated based on user actions and command results.
- Configuration Loading:
– At startup, the application loads a “config.yaml” file (from OS-specific locations) to configure key mappings and UI thresholds (like single pane width) which influences UI rendering decisions.

##### Important Architectural Patterns and Principles
- Modular Design:
– The separation between the core TUI application, command processing, and configuration allows for flexibility and customizability.
- Clear Separation of Concerns:
– UI components, command modules, and configuration handling are clearly separated, making it easier to extend or modify individual parts without affecting the others.
- Use of External Libraries/Forks:
– The project leverages forks of terminal UI libraries (nottui and notty) indicating a design decision to build on a robust, possibly customized UI rendering foundation.
- Integration with External Services:
– By relying on the jujutsu CLI, the project separates version control logic (handled externally) from the TUI, focusing on UI/UX and input processing.

##### Extra Details
- Build and development infrastructure (Nix, GitHub workflows, dune build scripts) in a separate “Development & Deployment” cluster if needed.

– The separation of the main TUI application into core modules (UI, commands, and configuration).
– The flow of user input through key mapping to command processing and eventual interaction with the external jujutsu CLI.
– The integration of commonly-collaborated libraries (forks of notty/nottui) for handling terminal-specific rendering.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        Terminal["Terminal Input"]:::terminal
    end

    subgraph "Configuration & Key Mapping"
        Config["Configuration Module"]:::config
        KeyMapping["Key Mapping Module"]:::config
    end

    subgraph "Command Processing"
        GraphCmd["Graph Commands Module"]:::command
        FileCmd["File Commands Module"]:::command
    end

    subgraph "Core Application"
        MainApp["Main Application (jj_tui)"]:::core
    end

    subgraph "UI/Rendering"
        Widgets["Internal Widgets"]:::ui
        Notty["Notty Fork"]:::ui_lib
        Nottui["Nottui Fork"]:::ui_lib
    end

    subgraph "External Services"
        Jujutsu["Jujutsu CLI Integration"]:::external
    end

    subgraph "Development & Infrastructure"
        Build["Build & Dev Infrastructure"]:::infra
    end

    Terminal -->|"keyPressed"| KeyMapping
    Config -->|"configures"| KeyMapping
    KeyMapping -->|"dispatchGraphCommand"| GraphCmd
    KeyMapping -->|"dispatchFileCommand"| FileCmd
    GraphCmd -->|"updates"| MainApp
    FileCmd -->|"updates"| MainApp
    GraphCmd -->|"executes"| Jujutsu
    FileCmd -->|"executes"| Jujutsu
    MainApp -->|"renders"| Widgets
    Widgets -->|"usesRendering"| Notty
    Widgets -->|"usesRendering"| Nottui

    classDef terminal fill:#a3e635,stroke:#333,stroke-width:2px;
    classDef config fill:#fef08a,stroke:#333,stroke-width:2px;
    classDef command fill:#93c5fd,stroke:#333,stroke-width:2px;
    classDef core fill:#fda4af,stroke:#333,stroke-width:2px;
    classDef ui fill:#fbcfe8,stroke:#333,stroke-width:2px;
    classDef ui_lib fill:#d8b4fe,stroke:#333,stroke-width:2px;
    classDef external fill:#a5b4fc,stroke:#333,stroke-width:2px;
    classDef infra fill:#bef264,stroke:#333,stroke-width:2px;

    click MainApp "https://github.com/faldor20/jj_tui/blob/master/jj_tui/bin/main.ml"
    click GraphCmd "https://github.com/faldor20/jj_tui/blob/master/jj_tui/bin/graph_commands.ml"
    click FileCmd "https://github.com/faldor20/jj_tui/blob/master/jj_tui/bin/file_commands.ml"
    click Widgets "https://github.com/faldor20/jj_tui/tree/master/jj_tui/lib/widgets"
    click Notty "https://github.com/faldor20/jj_tui/tree/master/forks/notty"
    click Nottui "https://github.com/faldor20/jj_tui/tree/master/forks/nottui"
    click Config "https://github.com/faldor20/jj_tui/blob/master/jj_tui/lib/config.ml"
    click KeyMapping "https://github.com/faldor20/jj_tui/blob/master/jj_tui/lib/key_map.ml"
    click KeyMapping "https://github.com/faldor20/jj_tui/blob/master/jj_tui/lib/key_map/key_map_new.ml"
    click Build "https://github.com/faldor20/jj_tui/blob/master/flake.nix"
```
