# billqk/gitlock_holmes architecture

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

- Interactive diagram: https://gitdiagram.com/billqk/gitlock_holmes
- Repository: https://github.com/billqk/gitlock_holmes

## Overview

##### Project type and purpose
- This is an Elixir “umbrella” application consisting of three OTP apps:
– gitlock_holmes_core: the domain-centric engine (complexity analysis, coupling detection, hotspot identification, reporters)
– gitlock_holmes_cli: a command-line interface that calls into core and prints results
– gitlock_holmes_phx: a Phoenix-based web application exposing core functionality over HTTP/HTML
- The overall goal is to ingest a Git repository, run a suite of analyses, and output reports (CSV, JSON, terminal, or web UI).

##### File structure for architecture clues
- Top-level umbrella: `apps/` containing three apps plus shared config.
- Core uses a hexagonal (ports-and-adapters) structure:
– `ports/`: definitions of external interfaces (complexity analyzer, VCS port, report port)
– `adapters/`: implementations for each port (Git adapter, complexity analyzers per language, CSV/JSON reporters)
– `domain/`: entities, values, and services encapsulating business rules
– `core/`: an investigation coordinator orchestrating domain services and adapters
- CLI and Phx apps each have a simple entry point (`main.ex` or Phoenix endpoint) that invokes core’s application module.
- No database—data comes from Git and flows through core into reporters or HTTP responses.

##### (minimal) README
- Use the file structure as the authoritative source for component boundaries and dependencies.

– GitlockHolmes_Umbrella (root)
– gitlock_holmes_core
- Domain Layer (Entities, Values, Services)
- Core/Coordinator (orchestration)
- Ports (ComplexityAnalyzerPort, VersionControlPort, ReportPort)
- Adapters (Git adapter, Complexity lang adapters, CSV/JSON reporters)
– gitlock_holmes_cli (CLI adapter)
– gitlock_holmes_phx (Web adapter)
– External Systems
- Git Repository (local or remote)
- Terminal (STDOUT)
- Web browser (HTTP client)
– CLI or Web UI → invokes Core.Application → Coordinator
– Coordinator → calls Domain.Services → fetches commits via VersionControlPort → uses Git adapter
– Services → dispatch to ComplexityAnalyzerPort → complexity lang adapters
– Services → apply coupling/hotspot algorithms → produce domain values
– Coordinator → hands results to ReportPort → JSON/CSV reporters or HTTP view templates or STDOUT
– Web adapter renders HTML/JSON and serves to browser
c. Architectural patterns
– OTP supervision trees per app
– Hexagonal architecture in core (ports & adapters)
– Layered domain-driven design (Entities/Values → Services → Orchestrator)
d. Key technologies
– Elixir/Erlang OTP
– Phoenix Framework (HTTP server, LiveView components)
– Mix umbrella project
– reporters (CSV & JSON libraries)
– underlying `git` CLI invoked via adapter

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GitRepo(("Git Repository")):::external
    Terminal(("Terminal")):::external
    Browser(("Web Browser")):::external

    %% Umbrella Root
    Umbrella["Umbrella Project\n(GitlockHolmes_Umbrella)"]:::core
    click Umbrella "https://github.com/billqk/gitlock_holmes/tree/main/apps/"

    %% Client Applications
    subgraph "CLI Application" 
        CLIMain["Main (main.ex)"]:::client
        CLIModule["CLI Module"]:::client
    end
    click CLIMain "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_cli/lib/main.ex"
    click CLIModule "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_cli/lib/gitlock_holmes_cli.ex"

    subgraph "Web Application (Phoenix)"
        PhxEntry["Phx Entry\n(gitlock_holmes_phx.ex)"]:::client
        PhxApp["Phoenix Application\n(application.ex)"]:::client
        Endpoint["Endpoint\n(endpoint.ex)"]:::client
        Router["Router\n(router.ex)"]:::client
        Controllers["Controllers\n(page, error_html, error_json)"]:::client
        Components["UI Components & Layouts"]:::client
    end
    click PhxEntry "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_phx/lib/gitlock_holmes_phx.ex"
    click PhxApp "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_phx/lib/gitlock_holmes_phx/application.ex"
    click Endpoint "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_phx/lib/gitlock_holmes_phx_web/endpoint.ex"
    click Router "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_phx/lib/gitlock_holmes_phx_web/router.ex"
    click Controllers "https://github.com/billqk/gitlock_holmes/tree/main/apps/gitlock_holmes_phx/lib/gitlock_holmes_phx_web/controllers"
    click Components "https://github.com/billqk/gitlock_holmes/tree/main/apps/gitlock_holmes_phx/lib/gitlock_holmes_phx_web/components"

    %% Core Application
    subgraph "Core Application\n(gitlock_holmes_core)" 
        subgraph "Domain Layer"
            Domain["Entities, Services, Values"]:::core
        end
        subgraph "Ports (Hexagonal Interfaces)"
            Ports["VersionControlPort,\nComplexityAnalyzerPort,\nReportPort"]:::core
        end
        subgraph "Adapters"
            VCSAdapter["Git Adapter"]:::adapter
            ComplexityAdapters["Complexity Adapters"]:::adapter
            Reporters["Reporters\n(CSV & JSON)"]:::adapter
        end
        Coordinator["Coordinator\n(core/coordinator.ex)"]:::core
        CoreApp["Application Entry\n(application.ex)"]:::core
    end
    click Domain "https://github.com/billqk/gitlock_holmes/tree/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/domain"
    click Ports "https://github.com/billqk/gitlock_holmes/tree/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/ports"
    click VCSAdapter "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/adapters/vcs/git.ex"
    click ComplexityAdapters "https://github.com/billqk/gitlock_holmes/tree/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/adapters/complexity"
    click Reporters "https://github.com/billqk/gitlock_holmes/tree/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/adapters/reporters"
    click Coordinator "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/core/coordinator.ex"
    click CoreApp "https://github.com/billqk/gitlock_holmes/blob/main/apps/gitlock_holmes_core/lib/gitlock_holmes_core/application.ex"

    %% Relationships
    Umbrella --> CLIMain
    Umbrella --> PhxEntry
    CLIMain --> Coordinator
    CLIModule --> Coordinator
    PhxEntry --> PhxApp
    PhxApp --> Router
    Router --> Endpoint
    Endpoint --> Controllers
    Controllers --> Coordinator
    Coordinator --> Ports
    Ports --> VCSAdapter
    VCSAdapter --> GitRepo
    Ports --> ComplexityAdapters
    ComplexityAdapters --> Coordinator
    Coordinator --> Reporters
    Reporters --> Terminal
    Controllers --> Browser
    Reporters --> Browser

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef adapter fill:#FFFACD,stroke:#000;
    classDef client fill:#FFA500,stroke:#000;
```
