# mattharrison/epub-css-starter-kit architecture

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

- Interactive diagram: https://gitdiagram.com/mattharrison/epub-css-starter-kit
- Repository: https://github.com/mattharrison/epub-css-starter-kit

## Overview

##### Project type and purpose
- This is an open-source CSS starter kit (library) for building EPUB-compatible stylesheets.
- It provides a base.css (compiled) and base.sass (source) to be used in EPUB authoring workflows (e.g., rst2epub, kindlegen).

##### File structure
- Top-level:
- README.rst – project overview, focus platforms, usage instructions
- notes.rst – internal notes or future ideas
- css/ – distribution folder containing compiled CSS
– base.css
- sass/ – source folder for maintainable SASS
– base.sass
- No traditional “frontend/backend” split—this is a styling library.
- No build scripts shown, but implied SASS→CSS compilation step.

##### README for additional insights
- Purpose: produce a CSS that “just works” across Kindle (.mobi), Nook, and iBooks.
- Workflow references: rst2epub, kindlegen, sample HTML/CSS tests, issue triage for reader/platform bugs.

a. Main components
- Source assets: sass/base.sass
- Build step: SASS compiler (e.g., sass CLI, libsass)
- Distribution assets: css/base.css
- Consumer tool: EPUB packager (e.g., rst2epub2)
- Converter: kindlegen / Calibre (epub→mobi)
- Target: eReader devices (Kindle, Nook, iBooks, etc.)
- Issue tracker / GitHub (for bug reports and patches)
b. Relationships and interactions
- Developer writes/edits .sass → passes into SASS compiler → outputs .css
- Book-authoring tool injects base.css into HTML/XHTML → packages into .epub
- Converter ingests .epub (with base.css) → outputs .mobi/.azk (Kindle)
- eReader opens the package and applies base.css → renders to user
- Issues flow back from reader testing into GitHub issues, driving patches to .sass
c. Architectural patterns / design principles
- Source-artifact separation (SASS source vs. compiled CSS)
- Single responsibility: CSS kit focuses exclusively on styling cross-reader EPUBs
- Extensibility: downstream authors can layer custom CSS atop the starter kit
- Feedback loop: issue tracker drives iterative CSS adjustments
d. Key technologies / libraries
- SASS (preprocessor)
- CSS (distribution)
- rst2epub2, Pandoc, Calibre/kindlegen (packaging & conversion)
- GitHub (source, issues)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository Components
    subgraph "Repository" 
        direction TB
        README["README.rst"]:::docs
        NOTES["notes.rst"]:::docs
        SASS["SASS Source\nsass/base.sass"]:::repo
        CSS["CSS Output\ncss/base.css"]:::repo
    end

    %% Build Pipeline
    subgraph "Build & Packaging" 
        direction TB
        COMPILER["SASS Compiler\n(e.g., libsass)"]:::external
        PACKAGER["EPUB Packager\n(rst2epub2, Pandoc)"]:::external
        EPUB[".epub Package"]:::external
        CONVERTER["Kindle Converter\n(Calibre, kindlegen)"]:::external
        MOBI[".mobi/.azk Output"]:::external
    end

    %% Extension Point
    AUTHOR["Author Custom CSS\n(override/base extension)"]:::external

    %% Target Devices
    subgraph "eReader Devices" 
        direction TB
        KINDLE["Kindle"]:::device
        NOOK["Nook"]:::device
        IBOOKS["iBooks"]:::device
    end

    %% Issue Tracker
    ISSUES["GitHub Issues"]:::external

    %% Flow
    SASS -->|"compile"| COMPILER
    COMPILER -->|"generates"| CSS
    CSS -->|"include in HTML"| PACKAGER
    CSS -->|"extend/override"| AUTHOR
    AUTHOR -->|"merged CSS"| PACKAGER
    PACKAGER -->|"outputs"| EPUB
    EPUB -->|"convert"| CONVERTER
    CONVERTER -->|"produces"| MOBI
    MOBI -->|"render on"| KINDLE
    MOBI -->|"render on"| NOOK
    MOBI -->|"render on"| IBOOKS
    KINDLE -.->|reports bugs| ISSUES
    NOOK -.->|reports bugs| ISSUES
    IBOOKS -.->|reports bugs| ISSUES
    ISSUES -.->|feedback patches| SASS

    %% Click Events
    click SASS "https://github.com/mattharrison/epub-css-starter-kit/blob/master/sass/base.sass"
    click CSS "https://github.com/mattharrison/epub-css-starter-kit/blob/master/css/base.css"
    click README "https://github.com/mattharrison/epub-css-starter-kit/blob/master/README.rst"
    click NOTES "https://github.com/mattharrison/epub-css-starter-kit/blob/master/notes.rst"

    %% Styles
    classDef repo fill:#cfe2ff,stroke:#375a7f,stroke-width:1px
    classDef external fill:#d1e7dd,stroke:#1e5631,stroke-width:1px
    classDef device fill:#ffe5b4,stroke:#c36,stroke-width:1px
    classDef docs fill:#f0f0f0,stroke:#777,stroke-width:1px
```
