Architecture decision: Python as the only core implementation with dual distribution (pip + npm via self-contained bundled runtime)

[calchiwo]

ExplainThisRepo is currently implemented and distributed through two ecosystems:

Python CLI → explain_this_repo/
Node.js CLI → node_version/

Both implement overlapping functionality and are maintained in ecosystem feature parity.

Current Structure

• "explain_this_repo/" → Python implementation
• "node_version/" → TypeScript implementation

Current Behavior

• Features are implemented in both Python and TypeScript
• Releases are published to PyPI and npm separately
• CLI behavior is exposed in both ecosystems
  Features are implemented in both ecosystems

Problem

Maintaining two implementations introduces:

• duplicated logic
• manual feature parity required
• risk of divergence between implementations
• increased maintenance cost

Direction

The Python implementation will be treated as the source of truth and will be the core implementation

The Node.js implementation will be refactored to act as a distribution layer for npm users, without duplicating core logic.

Purpose of this discussion

This discussion documents the current architecture and the planned direction of the project.
Feedback on potential risks or edge cases is welcome.

[Spectra010s]

This actually make sense, since the project has moved from using the python and node runners to executables, it will be best to drop the node runner and just bundle the executable

Perfectly making it synced and a source of truth without having to deal with multiple language dependencies

[calchiwo]

Target Architecture

• Python is the single source of truth for all core logic and the only core implementation
• npm distribution will act as a launcher with a bundled Python runtime
• TypeScript will not contain duplicated implementation logic

npm Behavior

The npm package will :

• include a bundled Python executable
• include a Node launcher script
• execute the compiled Python binary with forwarded CLI arguments

Node:

• detects OS
• executes the Python binary
• passes CLI arguments
• returns output to user

Python Packaging

• Python will be compiled into a standalone executable
• builds will be generated per OS for:
  • macOS
  • Linux
  • Windows
• no dependency on system Python or pip for npm users

Distribution

pip install explainthisrepo → standard Python distribution, pip path, normal Python install, entry point exposes CLI

npm install -g explainthisrepo → bundled runtime distribution ships bundled binary, no Python required, same CLI behavior

Both paths expose the same CLI behavior.

[calchiwo]

Migration Plan

• Stabilize Python implementation as the source of truth and only core implementation
  Build standalone Python binaries per platform
• Integrate binaries into the npm package
• Update Node CLI to execute the Python binary
• Gradually remove TypeScript logic
• Validate parity during transition
• Deprecate the TypeScript implementation (node_version/)

Risks

• Cross-platform binary inconsistencies
• Larger npm package size
• Increased build complexity
• Ensuring consistent CLI behavior across distributions

Success Criteria

what “done” means:

• Python is the only core implementation
• npm CLI works without requiring Python installation
• pip CLI continues to work independently
  No feature duplication remains across implementations

[calchiwo]

Execution & Pipeline Design

This system is not two implementations. It is one core system with two distribution layers.

Python is the source of truth. Everything else depends on it.

Core Principle

• Python owns all runtime behavior

• Node does not implement logic

• Node only resolves, installs, and launches the Python core

• No feature is allowed to exist in Node without existing in Python first.

Execution Flow

1. User runs command (explainthisrepo ...)

2. Node CLI entrypoint executes

3. Node resolves environment:

• checks for embedded Python binary

• verifies version compatibility

• validates platform support

4. Node passes raw arguments directly to Python

5. Python handles:

• config loading

• provider selection

• repo analysis

• LLM interaction

• output generation

6. Python writes output to:

• stdout for user display

• filesystem when required (e.g. EXPLAIN.md)

7. Exit code is returned unchanged

Node does not transform output. It only forwards it.

Binary Distribution Pipeline

The system ships as a multi-target build:

Python core packaged as a standalone executable per OS

Node package acts as a launcher and installer

Build pipeline:

1. Build Python binary per target:

• macOS

• Linux

• Windows

2. Package binaries into Node distribution:

• embed or download on first run

• verify checksums

3. Publish artifacts:

• PyPI for Python users

• npm for Node users

4. CI enforces:

• identical version across both packages

• successful binary execution tests per platform

Source of Truth

• All business logic lives in Python

• Node mirrors commands, not logic

• Any new feature must be implemented in Python first

• If a feature is not in Python, it does not exist.

Command Pipeline

Commands are unified and passed directly:

init

• --doctor

• --quick

• --simple

• --detailed

• --stack

• --llm

any future flags

Flow:

• Node parses CLI arguments only to forward them

• Python interprets and executes behavior

Configuration Pipeline

Single config system:

Priority order:

1. Local project config

2. Environment variables

3. CLI flags

Rules:

• Config logic exists only in Python

• Node does not re-implement precedence

• Same config behavior across npm and pip

Provider & Model Pipeline

Python owns provider abstraction

Supported providers:

• Gemini

• OpenAI

• Anthropic

• Ollama

• Groq

• OpenRouter

Pipeline:

1. User selects provider

2. Python resolves provider config

3. Python executes request

4. Response flows back through unified output system

• Adding a new provider requires:

• Python implementation only

• No Node changes

Local Execution Pipeline

For local directories:

• Python handles filesystem traversal

• Python determines repository structure

• Python analyzes codebase

Node does not touch local paths beyond passing input.

Failure Handling Pipeline

Failures are handled inside Python:

• controlled error messages

• consistent exit codes

• no silent failures

Node:

• propagates errors as-is

• does not intercept or modify

Release Pipeline

Single version system:

• One version tag

• One release cycle

• Two distribution outputs

CI pipeline:

1. Run tests on Python core

2. Build binaries for all platforms

3. Run smoke tests on binaries

4. Publish to PyPI

5. Publish to npm

6. Validate installation flow end-to-end

Versioning & Compatibility

• Python defines version

• Node mirrors version

• Both must always match

No independent versioning.

Key Guarantees

• No duplicated core logic

• No behavioral drift between npm and pip

• Same output regardless of entrypoint

• Same feature set across all distributions

• Python remains the only system that matters at runtime

Hard Boundary

Node is infrastructure.

Python is product.

No exceptions.

[calchiwo]

Decision finalized and implemented.

Python is now the only core runtime.

Node no longer contains any implementation logic. It acts strictly as a thin launcher that resolves and executes the bundled Python binary.

The full execution pipeline is now:

• Node → resolve platform + binary
• Node → forward args
• Python → handle all logic (config, providers, analysis, output)
• Python → return stdout + exit code unchanged

Binary distribution is in place:

• PyInstaller builds per platform
• Binaries are staged into the npm package
• npm distributes prebuilt binaries (no Python required)
• pip continues to distribute the source package

All core logic duplication between Node and Python has been removed.

Versioning is unified across npm and PyPI.

Docs, CLI behavior, and release pipeline have been updated to reflect this architecture.

Legacy Node runtime has been removed from execution and isolated in _legacy/.

This is no longer a dual-runtime system.

Python is the product.
Node is infrastructure.

Closes #208