How billqk/gitlock_holmes works
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