# jbrinkman/ghi architecture

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

- Interactive diagram: https://gitdiagram.com/jbrinkman/ghi
- Repository: https://github.com/jbrinkman/ghi

## Overview

##### Main Components
- CLI Interface: Represented by the main executable (main.go) and the individual command implementations found under the cmd/ directory (auth.go, pr/pullrequest.go, review.go, view.go).
- GitHub Client: The pkg/clients package (specifically pkg/clients/github.go) which handles communication with the GitHub API.
- GitHub Functionality: The pkg/github package encapsulates additional logic for processing, displaying, and formatting GitHub data.
- Database Interaction: The pkg/db package manages interactions with the Turso/LibSQL database used for tracking review history.
- Logging: The pkg/logger package provides logging functionality which is used by various commands to log debug information.
- External Services: The GitHub API and Turso/LibSQL database (set up via the auth commands) should be depicted as external systems interacting with your tool.

##### Relationships and Interactions
- When executing a command (e.g., pr, view, review, auth), the command layer invokes the corresponding functionality in the pkg/ packages.
- For example, the pr command leverages pkg/clients and pkg/github to fetch pull request data.
- The view command may optionally log the review actions through pkg/db, indicating an interaction with the database layer.
- The auth command specifically configures and interacts with the database settings by taking user input and updating/storing credentials.
- GitHub API – for fetching pull request details, filtering by author/reviewer.
- Turso/LibSQL – for persisting review logs as defined in the database schema provided in the README.
- The logging system is cross-cutting, capturing activities from all commands. The pkg/logger should have drawn connections to all parts that support the --debug functionality.

##### Architectural Patterns and Design Principles
- Modular design: Split into command handlers (in cmd/) and underlying business logic (in pkg/) for easier testing and maintenance.
- Separation of concerns: Distinct layers exist with CLI (command parsing and user interface), a client layer (API calls), data processing, and persistence (database).
- Extensibility: The design supports additional commands or external integrations (such as additional branches for GitHub data retrieval) without major rework.

##### Relevant Technologies and Frameworks
- Go as the programming language.
- GitHub API as the external web service.
- Turso/LibSQL as a local database solution for review logging.
- YAML for configuration files.
- GitHub Actions (visible in the .github/workflows directory) to handle CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        cli_main("CLI Entry (main.go)"):::cli
        cmd_root("Command: Root (cmd/root.go)"):::cli
        cmd_auth("Command: Auth (cmd/auth.go)"):::cli
        cmd_pr("Command: Pull Request (cmd/pullrequest.go)"):::cli
        cmd_review("Command: Review (cmd/review.go)"):::cli
        cmd_view("Command: View (cmd/view.go)"):::cli
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        api_client("API Client (pkg/clients/github.go)"):::service
        subgraph "GitHub Functionality"
            gh_core("GitHub Core (pkg/github/github.go)"):::service
            gh_display("GitHub Display (pkg/github/display.go)"):::service
        end
        db_layer("Database Layer (pkg/db/db.go)"):::db
        logger("Logger (pkg/logger/logger.go)"):::logger
    end

    %% External Systems
    subgraph "External Systems"
        github_api("GitHub API"):::external
        libsql("Turso/LibSQL Database"):::external
    end

    %% Connections from CLI Layer to Business Logic
    cli_main -->|"routes"| cmd_root
    cli_main -->|"routes"| cmd_auth
    cli_main -->|"routes"| cmd_pr
    cli_main -->|"routes"| cmd_review
    cli_main -->|"routes"| cmd_view

    %% Command handlers interactions
    cmd_auth -->|"updates|configuration"| db_layer
    cmd_pr -->|"fetches pull request data"| api_client
    cmd_review -->|"logs review"| db_layer
    cmd_view -->|"retrieves review logs"| db_layer

    %% Business logic interactions
    api_client -->|"calls"| github_api
    api_client -->|"processes"| gh_core
    gh_core -->|"formats and relays"| gh_display

    %% Database interactions
    db_layer -->|"persists logs"| libsql

    %% Logger integration (cross-cutting)
    cmd_auth -->|"logs"| logger
    cmd_pr -->|"logs"| logger
    cmd_review -->|"logs"| logger
    cmd_view -->|"logs"| logger
    api_client -->|"logs"| logger
    gh_core -->|"logs"| logger
    db_layer -->|"logs"| logger

    %% Click Events
    click cli_main "https://github.com/jbrinkman/ghi/blob/main/main.go"
    click cmd_root "https://github.com/jbrinkman/ghi/blob/main/cmd/root.go"
    click cmd_auth "https://github.com/jbrinkman/ghi/blob/main/cmd/auth.go"
    click cmd_pr "https://github.com/jbrinkman/ghi/blob/main/cmd/pullrequest.go"
    click cmd_review "https://github.com/jbrinkman/ghi/blob/main/cmd/review.go"
    click cmd_view "https://github.com/jbrinkman/ghi/blob/main/cmd/view.go"
    click api_client "https://github.com/jbrinkman/ghi/blob/main/pkg/clients/github.go"
    click gh_core "https://github.com/jbrinkman/ghi/blob/main/pkg/github/github.go"
    click gh_display "https://github.com/jbrinkman/ghi/blob/main/pkg/github/display.go"
    click db_layer "https://github.com/jbrinkman/ghi/blob/main/pkg/db/db.go"
    click logger "https://github.com/jbrinkman/ghi/blob/main/pkg/logger/logger.go"

    %% Styles
    classDef cli fill:#fff9c4,stroke:#333,stroke-width:2px;
    classDef service fill:#bbdefb,stroke:#333,stroke-width:2px;
    classDef db fill:#c8e6c9,stroke:#333,stroke-width:2px;
    classDef logger fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
