# jwtor7/deck-builder architecture

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

- Interactive diagram: https://gitdiagram.com/jwtor7/deck-builder
- Repository: https://github.com/jwtor7/deck-builder

## Overview

##### Project Type & Purpose
- Decker is a CLI-based developer tool written in Python that transforms plain-text outlines into well-structured Markdown slide decks (Marp/Reveal.js), handouts, run-of-show timelines, and metadata.
- It’s not a web app or microservice; it’s a command-line pipeline tool with pluggable templates and an offline LLM (Ollama) integration.

##### File Structure Analysis
- Top-level:
- decker.py — executable entrypoint
- decker/ — core package
- templates/ — sample YAML templates
- examples/ — sample outlines
- decker.config.yml.example — default configuration schema
- tests — test_decker.py, test_v2.py
- Inside decker/:
- cli.py — argument parsing & command dispatcher
- pipeline.py — orchestrates the end-to-end process
- parser.py — reads & tokenizes outline text
- llm.py — calls the Ollama API for content generation
- formatter.py — applies Marp or Reveal formatting rules
- writers.py — writes Markdown, JSON outputs
- validator.py — runs post-generation quality checks
- templates.py — loads built-in & custom template definitions
- utils.py — helper functions

##### README Insights
- Describes a clear step-by-step build → preview → ros workflow.
- Emphasizes configuration via decker.config.yml.
- Lists output artifacts (deck.md, handout.md, run_of_show.md, meta.json).
- Shows a minimal “Architecture” section mapping modules.

##### Components
a. CLI Layer
- decker.py
- cli.py
b. Orchestration Layer
- pipeline.py
c. Processing Modules
- Parser (parser.py)
- Template Loader (templates.py)
- LLM Client (llm.py)
- Formatter (formatter.py)
- Validator (validator.py)
- Writers (writers.py)
- Utils (utils.py)
d. Configuration
- decker.config.yml (defaults + overrides)
e. External Dependencies
- Ollama (local LLM service)
- Marp CLI (optional PDF/preview)
f. I/O
- Input: outline file or inline text + templates/*.yml
- Output: outputs/<timestamp>/{deck.md, handout.md, run_of_show.md, meta.json}

##### Relationships & Data Flows
1. User invokes decker.py → CLI parses flags (cli.py).
2. CLI calls pipeline.build() in pipeline.py.
3. Pipeline loads configuration.
4. Pipeline calls parser.parse() → returns structured outline.
5. Pipeline calls templates.load() → selects template spec.
6. Pipeline sends outline + template to llm.generate() → receives raw slide content.
7. Pipeline passes raw content through validator.validate().
8. Pipeline hands validated content to formatter.format() → applies Marp/Reveal syntax.
9. Pipeline triggers writers.write_all() → writes deck.md, handout.md, run_of_show.md, meta.json.
10. CLI returns success or error (with trace logs if requested).

##### Architectural Patterns & Design Principles
- Modular pipeline (each stage is a separate module).
- Single-responsibility principle (parser, llm, formatter, writer are decoupled).
- Plugin/extensibility via templates.py (YAML-driven templates).
- Deterministic output via seed parameter.
- Offline-first design (local Ollama service with fallback models).
- Clear separation of concerns: CLI vs orchestration vs processing vs I/O.

##### Technologies & Frameworks
- Python 3.11+
- Ollama LLM API
- Marp Markdown & Reveal.js syntax
- YAML for template definitions
- pytest for tests (test_decker.py, test_v2.py)

##### Essential Elements Checklist
- [ ] External service: Ollama
- [ ] Inputs: outline file, YAML templates, config file
- [ ] Outputs: deck.md, handout.md, run_of_show.md, meta.json

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer
    subgraph "User & CLI Layer"
        direction TB
        User["User"]:::external
        DeckEntry["decker.py"]:::cli
        Cli["cli.py"]:::cli
    end

    %% Core Orchestration
    subgraph "Core Package"
        direction TB
        Pipeline["pipeline.py"]:::internal
        subgraph "Processing Modules"
            direction TB
            Parser["parser.py"]:::internal
            TemplateLoader["templates.py"]:::internal
            LLMClient["llm.py"]:::internal
            Validator["validator.py"]:::internal
            Formatter["formatter.py"]:::internal
            Writers["writers.py"]:::internal
        end
        Utils["utils.py"]:::internal
    end

    %% Configuration & Examples
    Config[(decker.config.yml)]:::config
    subgraph "File System I/O"
        direction TB
        TemplatesFs["templates/*.yml"]:::fs
        ExamplesFs["examples/*.txt"]:::fs
        OutputsFs["outputs/<timestamp>/\n{deck.md, handout.md,\nrun_of_show.md, meta.json}"]:::fs
    end

    %% External Services
    Ollama(("Ollama LLM")):::external
    MarpCLI(("Marp CLI\n(optional preview)")):::external

    %% Data Flows
    User -->|invokes| DeckEntry
    DeckEntry -->|"dispatch args"| Cli
    Cli -->|"calls build()"| Pipeline
    Config -.->|"loads config"| Pipeline
    ExamplesFs -->|"input outline"| Parser
    Parser -->|"parsed outline"| Pipeline
    Pipeline -->|"parse stage"| Parser
    Pipeline -->|"load template"| TemplateLoader
    TemplatesFs -->|"YAML templates"| TemplateLoader
    Pipeline -->|"LLM prompt"| LLMClient
    LLMClient -->|"raw content"| Pipeline
    Pipeline -->|"validate content"| Validator
    Validator -.->|"uses utils"| Utils
    Validator -->|"validated content"| Pipeline
    Pipeline -->|"format slides"| Formatter
    Formatter -->|"formatted slides"| Pipeline
    Pipeline -->|"write outputs"| Writers
    Writers -->|"output files"| OutputsFs
    Pipeline -->|"optional preview"| MarpCLI
    LLMClient -->|"calls service"| Ollama

    %% Click Events
    click DeckEntry "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker.py"
    click Cli "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/cli.py"
    click Pipeline "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/pipeline.py"
    click Parser "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/parser.py"
    click TemplateLoader "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/templates.py"
    click LLMClient "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/llm.py"
    click Formatter "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/formatter.py"
    click Validator "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/validator.py"
    click Writers "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/writers.py"
    click Utils "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker/utils.py"
    click Config "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/decker.config.yml.example"
    click TemplatesFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/templates/academic.yml"
    click TemplatesFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/templates/sales-demo.yml"
    click ExamplesFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/examples/sample-outline.txt"
    click ExamplesFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/examples/sales-pitch.txt"
    click ExamplesFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/examples/technical-talk.txt"
    click OutputsFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/test_decker.py"
    click OutputsFs "https://github.com/jwtor7/deck-builder/blob/claude/outline-to-markdown-slides-011CUrHZAZckFEEbqvj5x76z/test_v2.py"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#2980B9,stroke-width:1px
    classDef internal fill:#D6EAF8,stroke:#1B4F72,stroke-width:1px
    classDef config fill:#ABEBC6,stroke:#196F3D,stroke-width:1px
    classDef external fill:#F5CBA7,stroke:#B9770E,stroke-width:1px,stroke-dasharray: 5 5
    classDef fs fill:#E5E7E9,stroke:#626567,stroke-width:1px,stroke-dasharray: 2 2
```
