# n3xem/gh-otui architecture

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

- Interactive diagram: https://gitdiagram.com/n3xem/gh-otui
- Repository: https://github.com/n3xem/gh-otui

## Overview

##### Project Type and Purpose
- Type: CLI tool / GitHub extension written in Go.
- Purpose: To provide an interactive fuzzy finder interface for browsing GitHub repositories and, when selected, triggering a ghq clone (if not already cloned). It uses caching to store repository information for faster access.
- External Dependencies: GitHub CLI (gh), ghq, fuzzy finder (preferably peco but can also use fzf).

##### Analyzing the File Structure and Its Implications
- Top-Level Files and Directories:
- main.go: Entry point for the tool.
- cmd/: Likely contains the command-line executor logic. For example, cmd/executor.go would orchestrate user interaction and command execution.
- github/: Contains a client (github/client.go) that presumably wraps GitHub API interactions (or calls to the GitHub CLI) to fetch repository information.
- cache/: Holds caching logic for repository listings (cache/cache.go) to reduce redundant API calls.
- models/: Contains domain models (for example, models/repository.go) that define the structure and behavior of repository data.
- Various README files in multiple languages and CI/CD configurations (.github/ directory) which show attention to multi-language support and continuous integration for the project.
- Architectural Patterns:
- Separation of concerns is evident: input handling and command execution in cmd, data models in models, API logic in github, and caching functionality in cache.
- Use of modularization to abstract interactions with external tools (ghq, fuzzy finder) and GitHub data retrieval.

- Main Components to Include:
- CLI Application Entry Point (main.go): Represents the starting point and command processing.
- Command Executor (cmd/executor.go): Handles CLI commands, user input, and interaction with external tools.
- Fuzzy Finder Integration: A component (conceptually part of the executor) that launches either peco or fzf for interactive repository selection.
- GitHub API Client (github/client.go): Responsible for fetching repository listings via GitHub CLI (gh) commands or API calls.
- Cache Module (cache/cache.go): Manages locally cached repository data (saved in a JSON file under ~/.config/gh/extensions/gh-otui/).
- Domain Models (models/repository.go): Defines repository information such as organization names, repository names, and local clone status.
- External Services:
○ GitHub CLI (gh) used to fetch data and issue commands.
○ ghq: Used for cloning repositories and verifying if a repository is already cloned.
○ Fuzzy Finder (peco or fzf): Used for user-selection from a list of repositories.

- Relationships and Data Flow:
- The CLI entry point triggers the command executor.
- The executor invokes the GitHub API Client to fetch repository data.
- Fetched data is passed to the cache component to maintain or update the local repository cache.
- The cached or freshly-fetched repository list is then presented to the user through the fuzzy finder interface.
- Once the user selects a repository, the executor checks (possibly using the models and the output of ghq) if the repository is cloned.
- If not yet cloned, the executor commands ghq to perform a clone operation.
- Finally, the selected local path is output (allowing the user to immediately change directories).

##### Detailed and Clear Illustration
- Do not hesitate to break down each sub-process:
- Sequence when caching repository data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Internal Modules"
        CLI["CLI Entry Point (main.go)"]:::internal
        Executor["Command Executor (cmd/executor.go)"]:::internal
        GitHubClient["GitHub API Client (github/client.go)"]:::internal
        CacheManager["Cache Manager (cache/cache.go)"]:::internal
        Models["Data Models (models/repository.go)"]:::internal
    end

    subgraph "External Services"
        GitHubCLI["GitHub CLI (gh)"]:::external
        Ghq["ghq"]:::external
        FuzzyFinder["Fuzzy Finder (peco/fzf)"]:::external
    end

    CLI -->|"triggers"| Executor
    Executor -->|"invokes"| GitHubClient
    GitHubClient -->|"calls"| GitHubCLI
    Executor -->|"updates"| CacheManager
    Executor -->|"utilizes"| Models
    Executor -->|"presentsDataTo"| FuzzyFinder
    FuzzyFinder -->|"userSelection"| Executor
    Executor -->|"checksCloneStatus"| Models
    Executor -->|"ifNotClonedThenClone"| Ghq
    Ghq -->|"clonesRepo"| Executor
    Executor -->|"outputsLocalPath"| CLI

    click CLI "https://github.com/n3xem/gh-otui/blob/main/main.go"
    click Executor "https://github.com/n3xem/gh-otui/blob/main/cmd/executor.go"
    click GitHubClient "https://github.com/n3xem/gh-otui/blob/main/github/client.go"
    click CacheManager "https://github.com/n3xem/gh-otui/blob/main/cache/cache.go"
    click Models "https://github.com/n3xem/gh-otui/blob/main/models/repository.go"

    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
```
