# openhandbookcommons/ohc-001-digital-literacy architecture

> Architecture diagram of the GitHub repository openhandbookcommons/ohc-001-digital-literacy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openhandbookcommons/ohc-001-digital-literacy
- Repository: https://github.com/openhandbookcommons/ohc-001-digital-literacy

## Overview

##### What the file tree implies about architecture
Key structural components in the tree:

- **Quarto project configuration**
- `_quarto.yml` (the root “build manifest”: project settings, book structure, output format options, etc.)
- `index.qmd` (book entry point; often defines metadata and landing content)

- **Content sources**
- `front-matter/*.qmd` (license, disclaimers, printing, contribute, preface)
- `chapters/partN/*.qmd` (main book content split by parts)

- **Assets**
- `cover/` (cover inputs; exact files not shown but directory exists)
- `fonts/` (contains `OFL.txt`; implies custom fonts may be bundled/used in PDF generation)

- **Custom build helper(s)**
- `scripts/add_cover.py` (Python script; likely post-processes PDFs to add/merge a cover or generate cover pages)

- **Build outputs**
- `_book/` is mentioned in README as output directory (not committed)

- **Dependencies / toolchain**
- Quarto (which internally uses Pandoc)
- LaTeX distribution (TinyTeX recommended)
- Python packages: `pyyaml`, `pypdf`, `reportlab` (strongly suggests PDF manipulation + YAML parsing + PDF generation)

- **Distribution / release practice**
- Rendered PDF is **not version-controlled**; uploaded as a **binary asset with each release** (so there’s a “release artifact” step outside the repo tree)

The README defines the “system workflow”:

##### Authoring Inputs (Source)
- `index.qmd`
- `front-matter/*.qmd`
- `chapters/**.qmd`
- (Optional: treat each “part” directory as a subcomponent)

##### Project Configuration
- `_quarto.yml` (book structure, format settings, metadata)

##### Asset Inputs
- `cover/` (cover images or templates)
- `fonts/` (font files / license; show as “Fonts (OFL-licensed)”)

##### Build Orchestrator
- **Quarto CLI** (`quarto render`)
- Internals worth explicitly showing (even if Quarto abstracts them):
- **Pandoc** (document conversion)
- **LaTeX Engine** (PDF compilation; TinyTeX distribution)

##### Custom Post-Processing
- `scripts/add_cover.py`
- Python libs: `pypdf` / `reportlab` (PDF creation/manipulation), `pyyaml` (likely reads config)

##### Build Artifacts
- `_book/` directory
- “Book PDF” (the final distributable)

##### Distribution
- “GitHub Release (binary asset upload)” (based on README note)

This decomposition is the “as many components as possible” version for clarity and accuracy.

- `.qmd` + `_quarto.yml` + assets → **Quarto Render**
- Quarto Render → (via Pandoc) → LaTeX → PDF output
- PDF output → `_book/` (artifact directory)
- `_book/<book>.pdf` → `scripts/add_cover.py` (if used after render) → “Final PDF with cover”
- Final PDF → “GitHub Release asset”

##### Architectural patterns / principles

- **Content-as-code**: book content versioned as `.qmd` sources
- **Declarative build configuration**: `_quarto.yml` defines structure and output settings
- **Toolchain pipeline**: Quarto → Pandoc → LaTeX → PDF
- **Artifact separation**: `_book/` output not committed; release attaches binary output
- **Extensible build**: custom Python script(s) for post-processing (cover/PDF manipulation)

- Quarto CLI
- Pandoc (as an internal step)
- LaTeX / TinyTeX
- Python + `pyyaml`, `pypdf`, `reportlab`
- GitHub Releases (distribution endpoint)

##### Left column: Inputs
- `index.qmd`
- `front-matter/*.qmd`
- `chapters/part*/**.qmd`
- `cover/`
- `fonts/`
- `_quarto.yml`

##### Middle column: Build Pipeline
- nested/annotated steps:
- Pandoc (conversion)
- LaTeX/TinyTeX (PDF compile)

##### Right column: Outputs
- `_book/` (output directory)
- “Rendered PDF (release artifact; not committed)”

##### Bottom or far-right: Distribution
- “GitHub Release (binary asset upload)”

##### Side branch
- `scripts/add_cover.py` (Python) connected between `_book/ PDF` and “Final PDF”
- Dependencies: `pypdf`, `reportlab`, `pyyaml`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actors / Context
  %% =========================
  DEV["Developer / CI Runner"]:::external
  TOOLS["Installed Toolchain\n(Quarto CLI + Pandoc + LaTeX/TinyTeX + Python)"]:::external
  GH["GitHub Releases\n(Binary PDF asset upload)"]:::external

  %% =========================
  %% Repository Boundary
  %% =========================
  subgraph "Repository: Open Handbook (Quarto Book Project)"
    direction TB

    subgraph "Documentation / Workflow"
      direction TB
      README["README.md\n(Build & publication workflow)"]:::doc
    end

    subgraph "Project Configuration"
      direction TB
      QUARTO_YML["_quarto.yml\n(Build manifest: book structure, formats, metadata)"]:::config
      INDEX["index.qmd\n(Book entry point)"]:::source
    end

    subgraph "Content Sources (.qmd)"
      direction TB

      subgraph "Front Matter"
        direction TB
        FM_DIR["front-matter/"]:::folder
        FM_CONTRIB["contribute.qmd"]:::source
        FM_DISCL["disclaimers.qmd"]:::source
        FM_LICENSE["license.qmd"]:::source
        FM_PREFACE["preface.qmd"]:::source
        FM_PRINT["printing.qmd"]:::source

        FM_DIR --> FM_CONTRIB
        FM_DIR --> FM_DISCL
        FM_DIR --> FM_LICENSE
        FM_DIR --> FM_PREFACE
        FM_DIR --> FM_PRINT
      end

      subgraph "Chapters"
        direction TB
        CH_DIR["chapters/"]:::folder

        P1["chapters/part1/"]:::folder
        P2["chapters/part2/"]:::folder
        P3["chapters/part3/"]:::folder
        P4["chapters/part4/"]:::folder
        P5["chapters/part5/"]:::folder
        P6["chapters/part6/"]:::folder
        P7["chapters/part7/"]:::folder
        P8["chapters/part8/"]:::folder

        CH_DIR --> P1
        CH_DIR --> P2
        CH_DIR --> P3
        CH_DIR --> P4
        CH_DIR --> P5
        CH_DIR --> P6
        CH_DIR --> P7
        CH_DIR --> P8
      end
    end

    subgraph "Assets"
      direction TB
      COVER["cover/\n(Cover inputs)"]:::asset
      FONTS["fonts/\n(Custom fonts)"]:::asset
      OFL["OFL.txt\n(Font license)"]:::doc

      FONTS --> OFL
    end

    subgraph "Custom Post-Processing"
      direction TB
      SCRIPTS_DIR["scripts/"]:::folder
      ADD_COVER["add_cover.py\n(Post-process PDF: add/merge cover)"]:::script
      PY_DEPS["Python libs\n(pyyaml, pypdf, reportlab)"]:::note

      SCRIPTS_DIR --> ADD_COVER
      ADD_COVER -.->|"uses"| PY_DEPS
    end

    subgraph "Build Outputs (not committed)"
      direction TB
      BOOK_DIR["_book/\n(Render output directory)"]:::artifact
      PDF_RAW["Rendered PDF\n(from Quarto)"]:::artifact
      PDF_FINAL["Final PDF w/ cover\n(Release artifact)"]:::artifact

      BOOK_DIR --> PDF_RAW
      PDF_RAW -.->|"optional_postprocess"| ADD_COVER
      ADD_COVER -.->|"writes"| PDF_FINAL
      PDF_FINAL --> BOOK_DIR
    end
  end

  %% =========================
  %% Build / Publishing Pipeline
  %% =========================
  subgraph "Build Pipeline (Quarto Rendering)"
    direction TB
    QCLI["Quarto CLI\n\"quarto render\""]:::build
    PANDOC["Pandoc\n(Conversion to TeX/PDF pipeline)"]:::build
    LATEX["LaTeX Engine / TinyTeX\n(PDF compilation)"]:::build

    QCLI -->|"invokes"| PANDOC
    PANDOC -->|"generates"| LATEX
    LATEX -->|"produces"| PDF_RAW
  end

  %% =========================
  %% Flows / Dependencies
  %% =========================
  DEV -->|"reads"| README
  DEV -->|"runs"| QCLI
  DEV -->|"runs_optional"| ADD_COVER

  TOOLS -.->|"provides"| QCLI
  TOOLS -.->|"provides"| LATEX
  TOOLS -.->|"provides"| ADD_COVER

  QUARTO_YML -->|"defines_TOC+formats"| QCLI
  INDEX -->|"source_content"| QCLI
  FM_DIR -->|"source_content"| QCLI
  CH_DIR -->|"source_content"| QCLI
  COVER -->|"asset_input"| QCLI
  FONTS -->|"asset_input"| QCLI

  BOOK_DIR -->|"contains"| PDF_FINAL
  PDF_FINAL -->|"upload_as_release_asset"| GH

  %% =========================
  %% Click Events (component_mapping)
  %% =========================
  click QUARTO_YML "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/_quarto.yml"
  click INDEX "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/index.qmd"

  click FM_DIR "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/front-matter/"
  click FM_CONTRIB "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/front-matter/contribute.qmd"
  click FM_DISCL "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/front-matter/disclaimers.qmd"
  click FM_LICENSE "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/front-matter/license.qmd"
  click FM_PREFACE "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/front-matter/preface.qmd"
  click FM_PRINT "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/front-matter/printing.qmd"

  click CH_DIR "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/"
  click P1 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part1/"
  click P2 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part2/"
  click P3 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part3/"
  click P4 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part4/"
  click P5 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part5/"
  click P6 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part6/"
  click P7 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part7/"
  click P8 "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/chapters/part8/"

  click COVER "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/cover/"
  click FONTS "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/fonts/"
  click OFL "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/fonts/OFL.txt"

  click SCRIPTS_DIR "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/scripts/"
  click ADD_COVER "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/scripts/add_cover.py"

  click README "https://github.com/openhandbookcommons/ohc-001-digital-literacy/blob/main/README.md"
  click BOOK_DIR "https://github.com/openhandbookcommons/ohc-001-digital-literacy/tree/main/_book/"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#111827,stroke:#374151,color:#F9FAFB,stroke-width:1px
  classDef doc fill:#0F172A,stroke:#38BDF8,color:#E0F2FE,stroke-width:1px
  classDef config fill:#6D28D9,stroke:#C4B5FD,color:#F5F3FF,stroke-width:1px
  classDef source fill:#1D4ED8,stroke:#93C5FD,color:#EFF6FF,stroke-width:1px
  classDef folder fill:#0B4A6F,stroke:#7DD3FC,color:#E0F2FE,stroke-width:1px
  classDef asset fill:#065F46,stroke:#6EE7B7,color:#ECFDF5,stroke-width:1px
  classDef build fill:#15803D,stroke:#86EFAC,color:#F0FDF4,stroke-width:1px
  classDef script fill:#C2410C,stroke:#FDBA74,color:#FFF7ED,stroke-width:1px
  classDef artifact fill:#374151,stroke:#9CA3AF,color:#F9FAFB,stroke-width:1px
  classDef note fill:#3F3F46,stroke:#A1A1AA,color:#FAFAFA,stroke-dasharray: 4 3,stroke-width:1px
```
