# tarekazabou/contextify architecture

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

- Interactive diagram: https://gitdiagram.com/tarekazabou/contextify
- Repository: https://github.com/tarekazabou/contextify

## Overview

1. **Repo shape: mixed-language toolchain**
   - This repository is not a single app; it has a **Python package** in `contextify/` and a **TypeScript/Node layer** in `src/` with compiled output in `out/`.
   - The Python side appears to be the core CLI/runtime, while the TypeScript side provides a CLI wrapper/extension integration and a bridge into the Python engine.

2. **Primary user entrypoints**
   - The main command-line entrypoint is `contextify/__main__.py`, which likely dispatches into `contextify/main.py`.
   - There are also shell/PowerShell launchers in `scripts/` and a Windows `.bat` wrapper, which makes the tool runnable from different environments without manual wiring.

3. **Core orchestration layer in Python**
   - `contextify/main.py` is the central coordinator for command execution.
   - `config.py` handles environment/config loading and default behavior.
   - `onboarding.py` manages setup/help/first-run flows.
   - `__init__.py` exposes package metadata and package-level entrypoints.

4. **Context collection and prompt assembly**
   - The core product behavior is: inspect the current repository, select relevant files, and generate a context-rich prompt or analysis report.
   - The README’s flags map to a context-selection pipeline: `--focus`, `--changed`, `--target`, `--tree-shake`, `--skeleton-context`, `--scope-function`, and `--git-aware`.
   - Sensitive-file filtering and `.gitignore` awareness are part of the filesystem scanning boundary, so the tool deliberately narrows what leaves the local repo.

5. **AI/provider abstraction**
   - `providers.py` is the provider layer that chooses between **Gemini, GitHub Copilot, OpenAI, Anthropic, or a local proxy**.
   - The repo treats provider selection as a configurable boundary, with priority rules based on available environment variables and optional explicit model selection.
   - `auth.py` supports the GitHub Copilot path, including the README-described two-stage token exchange and header handling.

6. **Enhancement/bridge boundary**
   - `enhancer_bridge.py` suggests a cross-runtime handoff, likely between the Python core and the TypeScript “enhancer” implementation.
   - In `src/core/enhancer.ts` and `src/core/pythonBridge.ts`, the Node side appears to coordinate with Python rather than reimplement the whole engine, implying a split between orchestration and language/runtime-specific integration.

7. **TypeScript/Node surface**
   - `src/cli/index.ts` is a Node CLI entrypoint, while `src/extension.ts` is the extension-facing integration point.
   - This layer is compiled into `out/`, so the checked-in JS is the distributable artifact, not the source of truth.
   - The Node side likely handles packaging, editor integration, and invoking the Python-side capabilities through the bridge.

8. **Analysis mode as a separate product path**
   - `--analyze` is a distinct workflow from prompt generation.
   - Static analysis produces architecture/structure/dependency/code-statistics style output, while `--analyze --ai` escalates that through an AI provider for deeper narrative analysis and recommendations.
   - This means the system has two high-level flows: **prompt generation** and **project analysis**.

9. **External dependencies and runtime concerns**
   - The project depends on **Python 3.9+** and a Node/TypeScript build chain (`package.json`, `tsconfig.json`, `package-lock.json`).
   - External integrations include clipboard support, Git history/diff inspection, environment variables, and the AI provider APIs themselves.
   - `requirements.txt` and `.env.example` indicate the Python runtime is expected to be environment-driven rather than hardcoded.

10. **Build and distribution boundary**
   - `src/` is source; `out/` is generated JavaScript with source maps.
   - That separation matters architecturally: the repo supports both development-time TypeScript editing and runtime delivery via compiled assets.
   - Tests are minimal in-tree (`tests/test_simple.py`), suggesting the current emphasis is on CLI/tooling behavior rather than a large application domain model.

11. **Operational data flow**
   - User input enters via CLI/extension → config/env are loaded → repository context is scanned and filtered → files/metadata are selected → provider/auth logic is applied if AI output is needed → final prompt or analysis is emitted.
   - Output can be routed to clipboard, stdout, or a file, so the final boundary is intentionally flexible for human-in-the-loop use.

Main entry points: [`contextify/main.py`](https://github.com/tarekazabou/contextify/blob/main/contextify/main.py) (Main orchestrator), [`src/core/pythonBridge.ts`](https://github.com/tarekazabou/contextify/blob/main/src/core/pythonBridge.ts) (Python bridge), [`package.json`](https://github.com/tarekazabou/contextify/blob/main/package.json) (Node package), [`src/cli/index.ts`](https://github.com/tarekazabou/contextify/blob/main/src/cli/index.ts) (Node CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python core"]
  node_py_entry(("CLI entry<br/>python entrypoint<br/>[__main__.py]"))
  node_py_main["Main orchestrator<br/>python coordinator<br/>[main.py]"]
  node_py_config["Config loader<br/>python config<br/>[config.py]"]
  node_py_onboarding["Onboarding<br/>python setup flow<br/>[onboarding.py]"]
  node_py_providers["Providers<br/>python provider layer<br/>[providers.py]"]
  node_py_auth["Copilot auth<br/>python auth<br/>[auth.py]"]
  node_py_bridge["Enhancer bridge<br/>python bridge<br/>[enhancer_bridge.py]"]
end

subgraph group_node["Node layer"]
  node_node_cli(("Node CLI<br/>ts entrypoint<br/>[index.ts]"))
  node_node_ext["Extension API<br/>ts integration<br/>[extension.ts]"]
  node_node_enhancer["Enhancer<br/>ts core<br/>[enhancer.ts]"]
  node_node_bridge["Python bridge<br/>ts bridge<br/>[pythonBridge.ts]"]
  node_out_cli["Built CLI<br/>compiled js<br/>[index.js]"]
  node_out_ext["Built extension<br/>compiled js<br/>[extension.js]"]
  node_out_enhancer["Built enhancer<br/>compiled js<br/>[enhancer.js]"]
  node_out_pybridge["Built bridge<br/>compiled js<br/>[pythonBridge.js]"]
end

subgraph group_ops["Operational surface"]
  node_scripts_install["Install scripts<br/>shell/ps1<br/>[install.sh]"]
  node_scripts_launch["Launchers<br/>bat/ps1<br/>[contextify.bat]"]
  node_requirements["Python deps<br/>dependency spec<br/>[requirements.txt]"]
  node_package["Node package<br/>package manifest<br/>[package.json]"]
end

node_py_entry -->|"dispatches"| node_py_main
node_py_main -->|"loads"| node_py_config
node_py_main -->|"guides"| node_py_onboarding
node_py_main -->|"selects"| node_py_providers
node_py_providers -->|"auth path"| node_py_auth
node_py_main -->|"bridges"| node_py_bridge
node_node_cli -->|"invokes"| node_node_bridge
node_node_ext -->|"uses"| node_node_enhancer
node_node_enhancer -->|"coordinates"| node_node_bridge
node_node_bridge -.->|"handoff"| node_py_bridge
node_node_bridge -.->|"executes"| node_py_main
node_out_cli -.->|"builds from"| node_node_cli
node_out_ext -.->|"builds from"| node_node_ext
node_out_enhancer -.->|"builds from"| node_node_enhancer
node_out_pybridge -.->|"builds from"| node_node_bridge
node_scripts_launch -->|"launches"| node_py_entry
node_scripts_install -->|"sets up"| node_package
node_package -->|"packages"| node_node_cli
node_package -->|"packages"| node_node_ext
node_requirements -->|"supports"| node_py_main

click node_py_entry "https://github.com/tarekazabou/contextify/blob/main/contextify/__main__.py"
click node_py_main "https://github.com/tarekazabou/contextify/blob/main/contextify/main.py"
click node_py_config "https://github.com/tarekazabou/contextify/blob/main/contextify/config.py"
click node_py_onboarding "https://github.com/tarekazabou/contextify/blob/main/contextify/onboarding.py"
click node_py_providers "https://github.com/tarekazabou/contextify/blob/main/contextify/providers.py"
click node_py_auth "https://github.com/tarekazabou/contextify/blob/main/contextify/auth.py"
click node_py_bridge "https://github.com/tarekazabou/contextify/blob/main/contextify/enhancer_bridge.py"
click node_node_cli "https://github.com/tarekazabou/contextify/blob/main/src/cli/index.ts"
click node_node_ext "https://github.com/tarekazabou/contextify/blob/main/src/extension.ts"
click node_node_enhancer "https://github.com/tarekazabou/contextify/blob/main/src/core/enhancer.ts"
click node_node_bridge "https://github.com/tarekazabou/contextify/blob/main/src/core/pythonBridge.ts"
click node_out_cli "https://github.com/tarekazabou/contextify/blob/main/out/cli/index.js"
click node_out_ext "https://github.com/tarekazabou/contextify/blob/main/out/extension.js"
click node_out_enhancer "https://github.com/tarekazabou/contextify/blob/main/out/core/enhancer.js"
click node_out_pybridge "https://github.com/tarekazabou/contextify/blob/main/out/core/pythonBridge.js"
click node_scripts_install "https://github.com/tarekazabou/contextify/blob/main/scripts/install.sh"
click node_scripts_launch "https://github.com/tarekazabou/contextify/blob/main/scripts/contextify.bat"
click node_requirements "https://github.com/tarekazabou/contextify/blob/main/requirements.txt"
click node_package "https://github.com/tarekazabou/contextify/blob/main/package.json"

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_entry,node_py_main,node_py_config,node_py_onboarding,node_py_providers,node_py_auth,node_py_bridge toneBlue
class node_node_cli,node_node_ext,node_node_enhancer,node_node_bridge,node_out_cli,node_out_ext,node_out_enhancer,node_out_pybridge toneAmber
class node_scripts_install,node_scripts_launch,node_requirements,node_package toneMint
```

## Components

### Python core

CLI runtime, config, scanning, provider selection, and AI/auth boundaries.

- [CLI entry](https://github.com/tarekazabou/contextify/blob/main/contextify/__main__.py): python entrypoint · Module entry that starts the Python command-line flow. · `contextify/__main__.py`
- [Main orchestrator](https://github.com/tarekazabou/contextify/blob/main/contextify/main.py): python coordinator · Central command dispatcher for prompt generation and analysis workflows. · `contextify/main.py`
- [Config loader](https://github.com/tarekazabou/contextify/blob/main/contextify/config.py): python config · Loads environment-driven settings and defaults. · `contextify/config.py`
- [Onboarding](https://github.com/tarekazabou/contextify/blob/main/contextify/onboarding.py): python setup flow · Handles first-run guidance and setup-related user flows. · `contextify/onboarding.py`
- [Providers](https://github.com/tarekazabou/contextify/blob/main/contextify/providers.py): python provider layer · Selects and configures AI backends such as Gemini, Copilot, OpenAI, Anthropic, or local proxy. · `contextify/providers.py`
- [Copilot auth](https://github.com/tarekazabou/contextify/blob/main/contextify/auth.py): python auth · Supports GitHub Copilot token exchange and request header handling. · `contextify/auth.py`
- [Enhancer bridge](https://github.com/tarekazabou/contextify/blob/main/contextify/enhancer_bridge.py): python bridge · Cross-runtime handoff between Python core and the Node enhancer surface. · `contextify/enhancer_bridge.py`

### Node layer

TypeScript source and compiled runtime for CLI and extension integration.

- [Node CLI](https://github.com/tarekazabou/contextify/blob/main/src/cli/index.ts): ts entrypoint · TypeScript command-line entrypoint used by the Node wrapper. · `src/cli/index.ts`
- [Extension API](https://github.com/tarekazabou/contextify/blob/main/src/extension.ts): ts integration · Editor/extension-facing integration surface. · `src/extension.ts`
- [Enhancer](https://github.com/tarekazabou/contextify/blob/main/src/core/enhancer.ts): ts core · Node-side enhancement coordination layer. · `src/core/enhancer.ts`
- [Python bridge](https://github.com/tarekazabou/contextify/blob/main/src/core/pythonBridge.ts): ts bridge · Invokes or coordinates with the Python engine from Node. · `src/core/pythonBridge.ts`
- [Built CLI](https://github.com/tarekazabou/contextify/blob/main/out/cli/index.js): compiled js · Distributable JavaScript output for the Node CLI. · `out/cli/index.js`
- [Built extension](https://github.com/tarekazabou/contextify/blob/main/out/extension.js): compiled js · Distributable JavaScript output for the extension surface. · `out/extension.js`
- [Built enhancer](https://github.com/tarekazabou/contextify/blob/main/out/core/enhancer.js): compiled js · Compiled output of the Node enhancement core. · `out/core/enhancer.js`
- [Built bridge](https://github.com/tarekazabou/contextify/blob/main/out/core/pythonBridge.js): compiled js · Compiled output of the Node-to-Python bridge. · `out/core/pythonBridge.js`

### Operational surface

Scripts, examples, and distribution helpers for setup and execution.

- [Install scripts](https://github.com/tarekazabou/contextify/blob/main/scripts/install.sh): shell/ps1 · Setup and installation helpers for local environments. · `scripts/install.sh`
- [Launchers](https://github.com/tarekazabou/contextify/blob/main/scripts/contextify.bat): bat/ps1 · Platform launch wrappers for running the tool from different shells. · `scripts/contextify.bat`
- [Python deps](https://github.com/tarekazabou/contextify/blob/main/requirements.txt): dependency spec · Python runtime dependencies and environment expectations. · `requirements.txt`
- [Node package](https://github.com/tarekazabou/contextify/blob/main/package.json): package manifest · Node/TypeScript build, packaging, and runtime metadata. · `package.json`

## Connections

- CLI entry → Main orchestrator: dispatches · Python module entry hands off to the main coordinator.
- Main orchestrator → Config loader: loads · Main flow reads environment and default configuration.
- Main orchestrator → Onboarding: guides · Main flow can invoke setup or first-run guidance.
- Main orchestrator → Providers: selects · Main flow chooses AI providers when generation or analysis needs them.
- Providers → Copilot auth: auth path · Copilot provider uses the dedicated authentication boundary.
- Main orchestrator → Enhancer bridge: bridges · Python core can hand off enhancement work across the runtime boundary.
- Node CLI → Python bridge: invokes · Node CLI routes execution through the bridge layer.
- Extension API → Enhancer: uses · Extension surface depends on the Node enhancement core.
- Enhancer → Python bridge: coordinates · Enhancer delegates Python-specific work through the bridge.
- Python bridge → Enhancer bridge: handoff · Node bridge connects to the Python bridge boundary.
- Python bridge → Main orchestrator: executes · Bridge ultimately drives the Python orchestrator.
- Built CLI → Node CLI: builds from · Compiled CLI is generated from the TypeScript source.
- Built extension → Extension API: builds from · Compiled extension is generated from the TypeScript source.
- Built enhancer → Enhancer: builds from · Compiled enhancer is generated from the TypeScript source.
- Built bridge → Python bridge: builds from · Compiled bridge is generated from the TypeScript source.
- Launchers → CLI entry: launches · Shell and PowerShell wrappers make the Python entrypoint easy to run.
- Install scripts → Node package: sets up · Install helpers support the Node toolchain and runtime setup.
- Node package → Node CLI: packages · Package manifest defines the Node CLI build and distribution.
- Node package → Extension API: packages · Package metadata also covers the extension surface.
- Python deps → Main orchestrator: supports · Python dependency spec supports the core runtime.