# avrabyt/fastdeck architecture

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

- Interactive diagram: https://gitdiagram.com/avrabyt/fastdeck
- Repository: https://github.com/avrabyt/fastdeck

## Overview

##### Project type and purpose
- Fastdeck is an open-source Python library (not a full-stack web app) whose primary purpose is to generate HTML slide decks programmatically.
- Key indicators:
- A `fastdeck/` package with `Presentation`, `Slide`, `Content` modules.
- README shows a pure-Python API that outputs HTML.
- Tests under `tests/`, no “frontend” or “backend” services.
- Docs under `docs/` and a GitHub Actions workflow to publish them.

##### File structure
Top-level:
- `.github/workflows/docs.yaml` – CI job to build and publish docs.
- `fastdeck/` – core library code (modules: `content.py`, `slide.py`, `presentation.py`).
- `tests/` – unit tests.
- `docs/` – pre-generated HTML documentation and search script.
- `resources/` – branding assets (logos).
- `fastdeck_demo_output/` – example output HTML.
- `setup.py`, `requirements.txt` – packaging and dependencies.

##### README for additional insights
- Describes API usage: create `Presentation`, add `Slide`, attach `Content`, then `save_html` or `to_html`.
- Mentions integration points: Reveal.js under the hood, optional chart integration via Plotly, video iframes, images.
- Highlights that Fastdeck powers an external “Fastdeck AI” app (but that app is outside this repo).

##### Components and interactions
1. Client Code (User’s Python script)
2. Fastdeck Library
- `Presentation` module
- `Slide` module
- `Content` module
3. Dependencies
- Reveal.js (JS/CSS for slides)
- Plotly (optional graph embedding)
4. Output
- Generated HTML files (`.html`)
5. Documentation Pipeline
- GitHub Actions CI → builds docs → publishes to GitHub Pages
6. Resources
- `resources/logos` asset store

- Client Code → calls → Fastdeck API
- `Presentation` orchestrates → multiple `Slide` instances
- `Slide` uses → `Content` to render HTML fragments
- Fastdeck Library → bundles Reveal.js assets + content → writes HTML to disk
- (Optional) Client Code imports Plotly → generates JSON → passed into Content → included in HTML
- CI (docs.yaml) → runs Sphinx/Markdown on `docs/` → pushes to GitHub Pages

c. Architectural patterns & principles:
- Modular design: clear separation of concerns among Presentation, Slide, and Content.
- Single responsibility: each class handles exactly one part of the slide-generation workflow.
- Extensibility points: ability to plug in new content types (charts, videos, images) via `Content` API.
- File-based I/O: no persistent database, simply generates static HTML.

- Python 3.x
- Reveal.js (static assets)
- Plotly (optional)
- GitHub Actions (CI/CD)
- pytest (testing)
- Sphinx/Markdown/HTML (docs)

##### Density and clarity
- Every essential element (API entry point, internal modules, external libraries, output).
- Don’t over-split: group related classes under a single “Fastdeck Library” container.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Code
    Client["Client Code<br/>(User's Python Script)"]:::external

    %% Core Library
    subgraph "Fastdeck Library"
        direction TB
        FDLib["fastdeck/"]:::core
        Presentation["Presentation"]:::core
        Slide["Slide"]:::core
        Content["Content"]:::core
    end

    %% Dependencies
    subgraph "External Dependencies"
        direction TB
        RevealJS["Reveal.js"]:::external
        Plotly["Plotly<br/>(Optional)"]:::external
    end

    %% Static Assets
    Resources["resources/logos/"]:::asset

    %% Output
    Output["Generated HTML Files<br/>(.html)"]:::asset

    %% Packaging & Tests
    subgraph "Packaging & Testing"
        direction TB
        Setup["setup.py"]:::tool
        Req["requirements.txt"]:::tool
        Tests["tests/test_fastdeck.py"]:::tool
    end

    %% Documentation Pipeline
    subgraph "Docs Publishing Pipeline"
        direction TB
        DocsCI[".github/workflows/docs.yaml"]:::tool
        DocsGen["Sphinx/Markdown → HTML"]:::docs
        DocsSite["docs/"]:::docs
    end

    %% Relationships
    Client -->|"calls API"| Presentation
    Presentation -->|"creates"| Slide
    Slide -->|"uses"| Content
    Content -->|"embeds assets"| RevealJS
    Content -->|"embeds charts"| Plotly
    Presentation -->|"bundles assets"| Resources
    FDLib --> Presentation
    FDLib --> Slide
    FDLib --> Content
    Presentation -->|"writes to"| Output
    DocsCI --> DocsGen
    DocsGen --> DocsSite

    %% Click Events
    click FDLib "https://github.com/avrabyt/fastdeck/tree/main/fastdeck/"
    click Presentation "https://github.com/avrabyt/fastdeck/blob/main/fastdeck/presentation.py"
    click Slide "https://github.com/avrabyt/fastdeck/blob/main/fastdeck/slide.py"
    click Content "https://github.com/avrabyt/fastdeck/blob/main/fastdeck/content.py"
    click Output "https://github.com/avrabyt/fastdeck/blob/main/fastdeck_demo_output/fastdeck_demo.html"
    click Resources "https://github.com/avrabyt/fastdeck/tree/main/resources/logos/"
    click DocsSite "https://github.com/avrabyt/fastdeck/tree/main/docs/"
    click DocsCI "https://github.com/avrabyt/fastdeck/blob/main/.github/workflows/docs.yaml"
    click Tests "https://github.com/avrabyt/fastdeck/blob/main/tests/test_fastdeck.py"
    click Setup "https://github.com/avrabyt/fastdeck/blob/main/setup.py"
    click Req "https://github.com/avrabyt/fastdeck/blob/main/requirements.txt"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef tool fill:#FFA500,stroke:#000,stroke-width:1px
    classDef asset fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef docs fill:#FFE4B5,stroke:#000,stroke-width:1px
```
