Contributing

Architecture

How project-brain is structured internally.

Module Map

CLI Layer  (cli.py, cli_ui.py, cli_help.py)
│
├── project_app  →  core/analyzer.py, core/summarizer.py, core/doctor.py
├── diff_app     →  core/differ.py, core/explainer.py, core/explainer_file.py
├── export_app   →  core/exporter.py
├── llm_app      →  llm/provider.py
└── community_app → community.py

Shared Infrastructure
├── core/config_loader.py    YAML config load + defaults
├── core/logger.py           Persistent log → .brain/logs.txt
├── core/results.py          HTML report generation
└── storage/storage.py       Data persistence helpers

Core Modules

core/analyzer.py

Recursive directory traversal, Python AST parsing, function/class/hash extraction. Writes to .brain/data.json.

core/differ.py

Git diff computation, changed file detection, function-level diff by comparing AST-extracted function bodies.

core/explainer.py

LLM-powered diff explanations, prompt construction, provider calls, caching, HTML report data.

core/explainer_file.py

Single-file and single-function explanation logic.

core/exporter.py

All export modes: full_code, file, dir, code_changes. Structured output format.

core/doctor.py

Orchestrates environment checks — delegates to doctor_checks/ submodules.

core/summarizer.py

Repository summary formatting (text/json/markdown modes).

core/config_loader.py

Loads brain.yaml, merges with DEFAULT_CONFIG recursively, validates schema.

llm/provider.py

Provider abstraction for OpenAI, Ollama, Gemini, HuggingFace — timeout handling, model listing, response normalization.

core/results.py

Generates interactive HTML diff reports with risk labels and semantic summaries.

Data Flow

Repository
  └─ brain project analyze
        └─ .brain/data.json         ← AST metadata
              └─ brain project summary  (reads data.json)
              └─ brain diff show        (reads git, optional data.json)
              └─ brain diff review      (reads git → calls LLM → .brain/reports/)
              └─ brain export full_code (reads filesystem → .brain/exports/)

Directory layout (source)

project-brain/
├── src/
│   └── project_brain/
│       ├── cli.py              ← CLI entry point
│       ├── cli_help.py         ← Help text strings
│       ├── cli_ui.py           ← Rich UI helpers
│       ├── community.py        ← Community command
│       ├── core/
│       │   ├── analyzer.py
│       │   ├── config_loader.py
│       │   ├── differ.py
│       │   ├── doctor.py
│       │   ├── doctor_checks/  ← environment, repo, llm, exports, analysis
│       │   ├── explainer.py
│       │   ├── explainer_file.py
│       │   ├── exporter.py
│       │   ├── logger.py
│       │   ├── results.py
│       │   └── summarizer.py
│       ├── llm/
│       │   └── provider.py
│       └── storage/
│           └── storage.py
├── tests/                      ← 18 pytest tests
├── brain.yaml                  ← default config
├── pyproject.toml
└── .github/
    ├── workflows/tests.yml     ← CI/CD
    └── ISSUE_TEMPLATE/

← Contributing