# brweinstein/runmd architecture

> Architecture diagram of the GitHub repository brweinstein/runmd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brweinstein/runmd
- Repository: https://github.com/brweinstein/runmd

## Overview

##### Project Type and Purpose
- This is a CLI tool (“runmd”) for treating Markdown files as executable notebooks.
- Primary implementation in Rust (under `/src`) for performance; a legacy Python implementation lives in `/core`.
- It locates fenced code blocks in `.md` files, spins up language-specific processes to run them, captures stdout/stderr, and injects standardized output blocks back into the Markdown.

##### File Structure
Top-level:
- Cargo.toml, `src/` → active Rust code
- `core/` → legacy Python code
- `tests/` → benchmarks and integration tests (Rust and Python)
- README, license, config files.
Rust modules (`src/`):
- `main.rs` → CLI entry point (argument parsing, subcommand dispatch)
- `core.rs` → Markdown parsing, block detection
- `runner.rs` → execution engine (serial/parallel)
- `languages.rs` → built-in language definitions
- `config.rs` → external config loading (`~/.config/runmd/languages.config`)
Python modules (`core/`):
- Mirror of Rust: `cli.py`, `core.py`, `runner.py`, `languages.py`, plus `utils.py`.

##### README for Additional Insights
- CLI flags (`-c`, `--init-config`, `-p`, etc.).
- Performance goals: parsing speed, parallel execution.
- Extensibility: user config file for custom commands.
- Workflow: find blocks → write temp files → run interpreters/compilers → capture outputs → rewrite Markdown.

a. Main Components
- CLI Layer (Rust: `main.rs` / Python: `cli.py`)
- Parser (Rust: `core.rs` / Python: `core.py`)
- Execution Engine (Rust: `runner.rs` / Python: `runner.py`)
- Language Configuration (Rust: `languages.rs` + `config.rs`; Python: `languages.py`)
- File System & OS process manager (spawns interpreters, handles temp files)
- External Config Store (`~/.config/runmd/languages.config`)
- Test Harness (benchmarks & integration tests in `tests/`)
b. Relationships & Data Flows
1. User invokes CLI → CLI parses args
2. CLI hands off to Parser → scanning the Markdown
3. Parser emits a list of code‐block jobs
4. Execution Engine schedules jobs (serial vs. parallel)
5. For each job:
– Consult Language Config → build command string
– Write temp file → spawn OS process → capture output
6. Engine returns results → Parser/Renderer inserts output blocks
7. CLI writes the transformed Markdown back to disk (or stdout)
8. Clear operation (`-c`) reverses the injection step.
c. Architectural Patterns & Principles
- Modular separation: parsing, execution, config.
- Pipeline pattern: source → transform → sink.
- Strategy pattern: per‐language execution strategy.
- Configurable extension point for new languages via YAML file.
- Parallel execution for throughput (thread pool or async).
d. Key Technologies & Frameworks
- Rust toolchain & Cargo
- Python 3.8+ (legacy)
- OS process spawning (`std::process::Command` / `subprocess`)
- YAML or similar for user config
- Markdown parsing library (custom in Rust/Python core)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pipeline
    subgraph "Pipeline"
        direction TB
        MD_IN["Markdown Input"]:::external
        CLI_RS["CLI Layer (Rust)"]:::rust
        PARSER_RS["Parser (Rust)"]:::rust
        EXEC_RS["Execution Engine (Rust)"]:::rust
        LANGDEF_RS["Language Definitions (Rust)"]:::rust
        CONFIG_RS["External Config Loader"]:::rust
        CONFIG_FILE["User Config File"]:::data
        OS_PROC["OS Process Manager"]:::extsys
        MD_OUT["Transformed Markdown Output"]:::external
    end

    MD_IN --> CLI_RS
    CLI_RS --> PARSER_RS
    PARSER_RS --> EXEC_RS
    EXEC_RS -->|consults| LANGDEF_RS
    EXEC_RS -->|loads| CONFIG_RS
    CONFIG_RS --> CONFIG_FILE
    EXEC_RS --> OS_PROC
    OS_PROC --> EXEC_RS
    EXEC_RS --> PARSER_RS
    PARSER_RS --> MD_OUT
    CLI_RS -->|writes output| MD_OUT

    %% Legacy Python (dotted)
    subgraph "Legacy Python Implementation" 
        style LegacyPython fill:none,stroke:#999,stroke-dasharray: 5 5
        direction TB
        CLI_PY["CLI Layer (Python)"]:::python
        PARSER_PY["Parser (Python)"]:::python
        EXEC_PY["Execution Engine (Python)"]:::python
        LANGDEF_PY["Language Definitions (Python)"]:::python
        UTIL_PY["Utility Functions"]:::python
    end

    MD_IN -.-> CLI_PY
    CLI_PY -.-> PARSER_PY
    PARSER_PY -.-> EXEC_PY
    EXEC_PY -.-> LANGDEF_PY
    EXEC_PY -.-> UTIL_PY
    EXEC_PY -.-> OS_PROC
    OS_PROC -.-> EXEC_PY
    EXEC_PY -.-> PARSER_PY
    PARSER_PY -.-> MD_OUT

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        BENCH["Benchmark Tests (Python)"]:::test
        INT_TEST["Integration Tests (Rust)"]:::test
        MD_TESTS["Sample Markdown Tests"]:::test
    end

    BENCH --> CLI_PY
    INT_TEST --> CLI_RS
    MD_TESTS --> PARSER_RS

    %% Click events
    click CLI_RS "https://github.com/brweinstein/runmd/blob/main/src/main.rs"
    click PARSER_RS "https://github.com/brweinstein/runmd/blob/main/src/core.rs"
    click EXEC_RS "https://github.com/brweinstein/runmd/blob/main/src/runner.rs"
    click LANGDEF_RS "https://github.com/brweinstein/runmd/blob/main/src/languages.rs"
    click CONFIG_RS "https://github.com/brweinstein/runmd/blob/main/src/config.rs"
    click CLI_PY "https://github.com/brweinstein/runmd/blob/main/core/cli.py"
    click PARSER_PY "https://github.com/brweinstein/runmd/blob/main/core/core.py"
    click EXEC_PY "https://github.com/brweinstein/runmd/blob/main/core/runner.py"
    click LANGDEF_PY "https://github.com/brweinstein/runmd/blob/main/core/languages.py"
    click UTIL_PY "https://github.com/brweinstein/runmd/blob/main/core/utils.py"
    click BENCH "https://github.com/brweinstein/runmd/blob/main/tests/benchmark.py"
    click INT_TEST "https://github.com/brweinstein/runmd/blob/main/tests/integration_tests.rs"
    click MD_TESTS "https://github.com/brweinstein/runmd/blob/main/tests/l01.md"
    click MD_TESTS "https://github.com/brweinstein/runmd/blob/main/tests/sample.md"

    %% Styles
    classDef rust fill:#c3e88d,stroke:#7f8c00
    classDef python fill:#f78c6c,stroke:#b34700
    classDef extsys fill:#89ddff,stroke:#0077aa,stroke-width:2px
    classDef data fill:#ffcb6b,stroke:#aa5500,stroke-width:2px
    classDef external fill:#eceff4,stroke:#444444,stroke-dasharray: 2 2
    classDef test fill:#e0af68,stroke:#8a4b00,stroke-width:2px
```
