# calchiwo/explainthisrepo architecture

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

- Interactive diagram: https://gitdiagram.com/calchiwo/explainthisrepo
- Repository: https://github.com/calchiwo/explainthisrepo

## Overview

1. **What this repository is**
   ExplainThisRepo is a developer tool for analyzing a codebase and producing a plain-English architecture summary. The core product is a CLI that inspects real repository signals—file tree, manifests, entrypoints, configs, and dependencies—then writes an `EXPLAIN.md` or prints shorter summaries.

2. **Main runtime boundary**
   The primary implementation lives in the Python package `explain_this_repo/`. That is the main execution path for published pip installs and the module entrypoint, while `node_version/` is a parallel TypeScript implementation with the same feature set and command shape.

3. **CLI entrypoint and command modes**
   `cli.py` / `__main__.py` form the user-facing entrypoint. The command supports multiple modes that change the output shape: full explanation, `--quick`, `--simple`, `--detailed`, and `--stack`, plus diagnostics and version checks.

4. **Input acquisition layer**
   Repository input is normalized before analysis. The tool accepts GitHub repo identifiers, full URLs, SSH-style clone URLs, issue/query links, and local paths; local analysis goes through `local_reader.py`, while remote GitHub access goes through `github.py`.

5. **Authentication and repo access**
   Private repository access and higher GitHub API rate limits are supported through GitHub token configuration. The init/config flow is handled by `init.py` and `config.py`, with setup instructions documented in `docs/GITHUB_TOKEN.md` and `docs/INIT.md`.

6. **Repository understanding pipeline**
   `repo_reader.py` is the main boundary for turning a repository into structured signals. It gathers high-value inputs from the filesystem or GitHub, then feeds them into stack detection and prompt generation rather than trying to summarize the entire tree uniformly.

7. **Tech-stack and signal detection**
   `stack_detector.py` and `stack_printer.py` extract a compact technology breakdown from project artifacts such as package manifests, lockfiles, configs, and entrypoint patterns. This is a separate, non-LLM path used for the `--stack` mode and as context for richer explanations.

8. **Prompting and generation**
   `prompt.py` and `generate.py` assemble the analysis into an LLM request. The output is deliberately architecture-oriented: it emphasizes boundaries, subsystems, and data flow rather than generic code commentary.

9. **Model/provider abstraction**
   `providers/` contains the LLM backend layer, with a shared base interface plus vendor-specific adapters for Anthropic, Gemini, Groq, Ollama, OpenAI, and OpenRouter. A registry selects the active provider so the rest of the CLI can stay model-agnostic.

10. **Output writing**
   `writer.py` controls whether the result is emitted to the terminal or persisted as `EXPLAIN.md`. This is the last step in the pipeline, so the rest of the system stays focused on analysis and model execution.

11. **Node.js distribution**
   `node_version/` mirrors the Python architecture with analogous files for CLI, config, repo reading, provider adapters, and generation. It exists as a second packaging/runtime boundary for users who prefer npm, npx, or standalone Node-based distribution.

12. **Web app and repository surface area**
   `apps/web/` is a separate Next.js marketing/documentation site, not part of the CLI runtime. It contains static landing-page components, Tailwind styling, and content that explains installation, modes, and usage.

13. **Build, release, and maintenance infrastructure**
   GitHub Actions in `.github/workflows/` handle CI and binary release packaging, which supports the standalone executables mentioned in the README. The repo also includes dependency automation, contribution docs, and release-oriented metadata to support distribution across Python, npm, and binary channels.

Main entry points: [`explain_this_repo/repo_reader.py`](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/repo_reader.py) (Repo reader), [`explain_this_repo/cli.py`](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/cli.py) (CLI entrypoint), [`.github/workflows`](https://github.com/calchiwo/explainthisrepo/blob/main/.github/workflows) (CI release), [`explain_this_repo/generate.py`](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/generate.py) (Generate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python runtime"]
  node_py_cli["CLI entrypoint<br/>python entrypoint<br/>[cli.py]"]
  node_py_main["Module entry<br/>python module<br/>[__main__.py]"]
  node_py_config["Config setup<br/>python config<br/>[config.py]"]
  node_py_init["Initializer<br/>python init<br/>[init.py]"]
  node_py_reader["Repo reader<br/>python pipeline<br/>[repo_reader.py]"]
  node_py_local["Local input<br/>python source reader<br/>[local_reader.py]"]
  node_py_github["GitHub input<br/>python source reader<br/>[github.py]"]
  node_py_stackdet{{"Stack detect<br/>python analyzer<br/>[stack_detector.py]"}}
  node_py_stackprint["Stack output<br/>python formatter<br/>[stack_printer.py]"]
  node_py_prompt["Prompt build<br/>python prompt<br/>[prompt.py]"]
  node_py_generate["Generate<br/>python orchestration<br/>[generate.py]"]
  node_py_writer["Output writer<br/>python output<br/>[writer.py]"]
  node_py_providers["Provider layer<br/>python llm adapters"]
end

subgraph group_node["Node runtime"]
  node_node_cli["CLI entrypoint<br/>ts entrypoint<br/>[cli.ts]"]
  node_node_reader["Repo reader<br/>ts pipeline<br/>[repo_reader.ts]"]
  node_node_generate["Generate<br/>ts orchestration<br/>[generate.ts]"]
  node_node_providers["Provider layer<br/>ts llm adapters"]
end

subgraph group_web["Web site"]
  node_web_app["Next.js site<br/>web frontend"]
  node_web_components["Site components<br/>web ui"]
end

subgraph group_infra["Build & release"]
  node_ci_release{{"CI release<br/>github actions<br/>[workflows]"}}
end

node_py_main -->|"loads"| node_py_cli
node_py_cli -->|"config"| node_py_config
node_py_cli -->|"init"| node_py_init
node_py_cli -->|"analyzes"| node_py_reader
node_py_reader -->|"local"| node_py_local
node_py_reader -->|"remote"| node_py_github
node_py_github -->|"auth"| node_py_config
node_py_reader -->|"signals"| node_py_stackdet
node_py_stackdet -->|"formats"| node_py_stackprint
node_py_reader -->|"context"| node_py_prompt
node_py_prompt -->|"request"| node_py_generate
node_py_generate -->|"model"| node_py_providers
node_py_generate -->|"output"| node_py_writer
node_node_cli -->|"analyzes"| node_node_reader
node_node_reader -->|"context"| node_node_generate
node_node_generate -->|"model"| node_node_providers
node_web_app -->|"uses"| node_web_components
node_ci_release -->|"builds"| node_py_cli
node_ci_release -->|"builds"| node_node_cli
node_ci_release -->|"tests"| node_web_app

click node_py_cli "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/cli.py"
click node_py_main "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/__main__.py"
click node_py_config "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/config.py"
click node_py_init "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/init.py"
click node_py_reader "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/repo_reader.py"
click node_py_local "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/local_reader.py"
click node_py_github "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/github.py"
click node_py_stackdet "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/stack_detector.py"
click node_py_stackprint "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/stack_printer.py"
click node_py_prompt "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/prompt.py"
click node_py_generate "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/generate.py"
click node_py_writer "https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/writer.py"
click node_py_providers "https://github.com/calchiwo/explainthisrepo/tree/main/explain_this_repo/providers"
click node_node_cli "https://github.com/calchiwo/explainthisrepo/blob/main/node_version/cli.ts"
click node_node_reader "https://github.com/calchiwo/explainthisrepo/blob/main/node_version/repo_reader.ts"
click node_node_generate "https://github.com/calchiwo/explainthisrepo/blob/main/node_version/generate.ts"
click node_node_providers "https://github.com/calchiwo/explainthisrepo/tree/main/node_version/providers"
click node_web_app "https://github.com/calchiwo/explainthisrepo/tree/main/apps/web/app"
click node_web_components "https://github.com/calchiwo/explainthisrepo/tree/main/apps/web/components"
click node_ci_release "https://github.com/calchiwo/explainthisrepo/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_cli,node_py_main,node_py_config,node_py_init,node_py_reader,node_py_local,node_py_github,node_py_stackdet,node_py_stackprint,node_py_prompt,node_py_generate,node_py_writer,node_py_providers toneBlue
class node_node_cli,node_node_reader,node_node_generate,node_node_providers toneAmber
class node_web_app,node_web_components toneMint
class node_ci_release toneRose
```

## Components

### Python runtime

Primary pip/module implementation for repository analysis and explanation.

- [CLI entrypoint](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/cli.py): python entrypoint · User-facing command dispatch and mode selection. · `explain_this_repo/cli.py`
- [Module entry](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/__main__.py): python module · Python package entrypoint for python -m execution. · `explain_this_repo/__main__.py`
- [Config setup](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/config.py): python config · Configuration loading and token setup flow. · `explain_this_repo/config.py`
- [Initializer](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/init.py): python init · First-run setup and repository bootstrap helpers. · `explain_this_repo/init.py`
- [Repo reader](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/repo_reader.py): python pipeline · Main boundary for collecting repository signals into structured input. · `explain_this_repo/repo_reader.py`
- [Local input](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/local_reader.py): python source reader · Reads and normalizes local filesystem repositories. · `explain_this_repo/local_reader.py`
- [GitHub input](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/github.py): python source reader · Fetches remote repository data and handles authenticated GitHub access. · `explain_this_repo/github.py`
- [Stack detect](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/stack_detector.py): python analyzer · Detects technology stack from manifests, lockfiles, configs, and entrypoints. · `explain_this_repo/stack_detector.py`
- [Stack output](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/stack_printer.py): python formatter · Prints compact stack summaries for stack mode. · `explain_this_repo/stack_printer.py`
- [Prompt build](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/prompt.py): python prompt · Assembles architecture-focused LLM prompts from repository signals. · `explain_this_repo/prompt.py`
- [Generate](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/generate.py): python orchestration · Coordinates model calls and explanation synthesis. · `explain_this_repo/generate.py`
- [Output writer](https://github.com/calchiwo/explainthisrepo/blob/main/explain_this_repo/writer.py): python output · Emits terminal summaries or writes EXPLAIN.md. · `explain_this_repo/writer.py`
- [Provider layer](https://github.com/calchiwo/explainthisrepo/tree/main/explain_this_repo/providers): python llm adapters · Shared abstraction for model backends and provider selection. · `explain_this_repo/providers`

### Node runtime

Parallel TypeScript implementation with the same command surface.

- [CLI entrypoint](https://github.com/calchiwo/explainthisrepo/blob/main/node_version/cli.ts): ts entrypoint · Node command dispatch and mode handling. · `node_version/cli.ts`
- [Repo reader](https://github.com/calchiwo/explainthisrepo/blob/main/node_version/repo_reader.ts): ts pipeline · Node-side repository signal collection and normalization. · `node_version/repo_reader.ts`
- [Generate](https://github.com/calchiwo/explainthisrepo/blob/main/node_version/generate.ts): ts orchestration · Node-side generation pipeline for model-backed explanations. · `node_version/generate.ts`
- [Provider layer](https://github.com/calchiwo/explainthisrepo/tree/main/node_version/providers): ts llm adapters · Node-side provider abstraction and backend adapters. · `node_version/providers`

### Web site

Next.js marketing and documentation surface.

- [Next.js site](https://github.com/calchiwo/explainthisrepo/tree/main/apps/web/app): web frontend · Marketing and documentation site separate from the CLI runtime. · `apps/web/app`
- [Site components](https://github.com/calchiwo/explainthisrepo/tree/main/apps/web/components): web ui · Landing-page sections and reusable content components. · `apps/web/components`

### Build & release

CI, packaging, and repo maintenance automation.

- [CI release](https://github.com/calchiwo/explainthisrepo/blob/main/.github/workflows): github actions · Automated testing and binary release packaging. · `.github/workflows`

## Connections

- Module entry → CLI entrypoint: loads · Module execution enters the CLI.
- CLI entrypoint → Config setup: config · CLI consults configuration and token setup.
- CLI entrypoint → Initializer: init · First-run setup flows through initializer.
- CLI entrypoint → Repo reader: analyzes · CLI routes repository requests into the reader pipeline.
- Repo reader → Local input: local · Local paths are read from the filesystem.
- Repo reader → GitHub input: remote · Remote repositories are fetched through GitHub.
- GitHub input → Config setup: auth · GitHub access uses token configuration.
- Repo reader → Stack detect: signals · Collected repo artifacts feed stack detection.
- Stack detect → Stack output: formats · Detected stack data is rendered for stack mode.
- Repo reader → Prompt build: context · Repository signals are shaped into prompt context.
- Prompt build → Generate: request · Prompt assembly feeds generation orchestration.
- Generate → Provider layer: model · Generation delegates to the provider abstraction.
- Generate → Output writer: output · Generated explanations are written or printed.
- CLI entrypoint → Repo reader: analyzes · Node CLI passes repository work to its reader.
- Repo reader → Generate: context · Read signals feed the generation pipeline.
- Generate → Provider layer: model · Generation uses the Node provider layer.
- Next.js site → Site components: uses · The site is composed from shared components.
- CI release → CLI entrypoint: builds · CI supports Python packaging and release artifacts.
- CI release → CLI entrypoint: builds · CI also packages the Node distribution.
- CI release → Next.js site: tests · Automation covers the site build and deployment surface.
