# verte-zerg/gession architecture

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

- Interactive diagram: https://gitdiagram.com/verte-zerg/gession
- Repository: https://github.com/verte-zerg/gession

## Overview

##### Project Type and Purpose
- Gession is a command-line application designed to manage tmux sessions.
- It offers two modes (Normal and Prime) and even a legacy CLI mode.
- Its core functionality includes an interactive TUI, fuzzy search for sessions, and integration with tmux through both modern control and classic CLI commands.

##### Key Components
a. Command-Line Interface (CLI) Entry Point:
- The cmd/gession/main.go file acts as the entry point. This initializes the application and determines which mode to run.

b. Interactive Terminal User Interface (TUI):
- Under internal/tui, you have components like mode.go, tui.go, update.go, and updatekey.go. This layer handles input (keyboard events), drawing the interface, and refreshing views.

c. Tmux Integration Layer:
- internal/tmux contains components such as adapters.go, climode, commandmode, and tmux.go. This layer abstracts the interaction with tmux, switching between control modes and CLI commands.

d. Session Management:
- internal/session and internal/sessiontree handle session-related logic, including creating, listing, and organizing tmux sessions.

e. Filesystem Interaction:
- internal/fsscanner is key to Prime mode where sessions may be created based on project directory structures.

f. Event Handling and Input Processing:
- internal/event and internal/keyboard help capture events (key presses, command inputs) and dispatch appropriate actions.

g. Utility/Supporting Packages:
- pkg/ansi, pkg/fuzzy, pkg/logging, and pkg/assert provide helper functionality such as styling terminal output, conducting fuzzy searches, logging information, and performing assertions during tests.

##### Relationships and Data Flow
- The user initiates Gession via the CLI (cmd/gession/main.go), which then sets up the TUI.
- The TUI (internal/tui) captures user inputs (keyboard events via internal/keyboard) and propagates events (via internal/event).
- These events trigger actions that may require interaction with tmux (via internal/tmux) to list, create, or manage sessions.
- For Prime mode, the filesystem scanner (internal/fsscanner) searches the file system for directories which are then used to create new sessions dynamically.
- Fuzzy search (pkg/fuzzy) assists in quickly filtering the session list.
- Throughout the process, logging (pkg/logging) provides diagnostic information and ANSI styling (pkg/ansi) is used to enhance TUI visuals.

##### Architectural Patterns and Design Principles
- Modular Design: The project is split into clearly defined domains (TUI, tmux adapters, session management, event handling), promoting separation of concerns.
- Command Routing and Event Handling: A pipeline that maps user interactions to underlying actions and tmux commands.
- Lightweight and Efficient: Emphasis on minimal dependencies and fast performance.

##### Final Checklist
- Clearly label main components: CLI, TUI, Event/Keyboard Handler, Session Manager, Tmux Integration, Filesystem Scanner, and Utility libraries.
- Short annotations (if possible) detailing responsibilities (e.g., “Handles user input”, “Executes tmux commands”, “Filters sessions with fuzzy search”).

## Diagram (Mermaid)

```mermaid
graph TD
    A["CLI Entry Point"]:::cli
    B["Interactive TUI"]:::tui
    C["Event Handling"]:::tui
    D["Keyboard Input"]:::tui

    subgraph "Session Management"
        E1["Session Logic"]:::backend
        E2["Session Tree"]:::backend
    end

    F["Tmux Integration"]:::backend
    G["Filesystem Scanner"]:::backend

    subgraph "Utility Modules"
        U1["ANSI Styling"]:::utility
        U2["Fuzzy Search"]:::utility
        U3["Logging"]:::utility
        U4["Assertions"]:::utility
    end

    A -->|"initializes"| B
    B -->|"capturesEvents"| C
    B -->|"capturesKeys"| D
    D -->|"sendsKeyEvent"| C
    C -->|"triggersSession"| E1
    C -->|"triggersTmux"| F
    E1 -->|"usesTree"| E2
    E1 <-->|"sessionControl"| F
    G -->|"createsSession"| E1
    B -->|"styles"| U1
    E1 -->|"filters"| U2
    F -->|"logs"| U3
    E1 -->|"asserts"| U4

    click A "https://github.com/verte-zerg/gession/blob/main/cmd/gession/main.go"
    click B "https://github.com/verte-zerg/gession/tree/main/internal/tui/"
    click C "https://github.com/verte-zerg/gession/blob/main/internal/event/event.go"
    click D "https://github.com/verte-zerg/gession/blob/main/internal/keyboard/keyboard.go"
    click E1 "https://github.com/verte-zerg/gession/blob/main/internal/session/session.go"
    click E2 "https://github.com/verte-zerg/gession/blob/main/internal/sessiontree/sessiontree.go"
    click F "https://github.com/verte-zerg/gession/tree/main/internal/tmux/"
    click G "https://github.com/verte-zerg/gession/blob/main/internal/fsscanner/fsscanner.go"
    click U1 "https://github.com/verte-zerg/gession/blob/main/pkg/ansi/ansi.go"
    click U2 "https://github.com/verte-zerg/gession/blob/main/pkg/fuzzy/fuzzy.go"
    click U3 "https://github.com/verte-zerg/gession/blob/main/pkg/logging/logging.go"
    click U4 "https://github.com/verte-zerg/gession/blob/main/pkg/assert/assert.go"

    classDef cli fill:#ffe699,stroke:#333,stroke-width:2px;
    classDef tui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef utility fill:#f9e79f,stroke:#333,stroke-width:2px;
```
