# eliblurr/bitcoinbook architecture

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

- Interactive diagram: https://gitdiagram.com/eliblurr/bitcoinbook
- Repository: https://github.com/eliblurr/bitcoinbook

## Overview

##### Project type and purpose
- This is not a traditional full-stack app or microservice; it’s an open-source documentation/book project ("Mastering Bitcoin")
- Primary purpose: maintain source (AsciiDoc chapters, appendices, code examples), build multiple output formats (HTML, PDF, EPUB, MOBI), run CI checks, publish releases, support translations

##### File structure
- Top-level AsciiDoc files (ch01.asciidoc … ch12.asciidoc, appendices *.asciidoc, book.asciidoc) are the content sources
- code/ folder holds runnable examples in C++, Python, Go, JavaScript for demonstration and CI testing
- theme/ directory contains presentation layers (CSS/layout HTML) for EPUB, PDF, MOBI builds
- tools/ includes helper scripts and reports for figure renaming, intake processing
- build & CI config: .travis.yml drives continuous integration; atlas.json, various HTML files for site structure; bookmarks like toc.html, ix.html for navigation

##### README for additional insights
- Describes Editions, how to read (book.asciidoc entry point), how to contribute (develop branch on GitHub), licensing

##### Main components
a. Content Source
– AsciiDoc chapters, appendices, front/back matter (cover.html, titlepage.html, toc.html, etc.)
– Images folder for figures
b. Code Examples
– code/ subfolders containing example scripts (Python, Go, C++, JS)
– tests or usage within chapters
c. Build Toolchain
– AsciiDoctor (or Antora/Asciidoctor PDF, EPUB, Kindle)
– theme templates for each format
– helper scripts in tools/
d. Continuous Integration
– Travis CI (.travis.yml) runs build sanity checks, example code linting/tests
e. Output Artifacts
– HTML website (via GitHub Pages or static host)
– PDF, EPUB, MOBI files (via AsciiDoctor plugins)
– GitHub releases (Edition tags)
f. External Services
– GitHub for source hosting, issues, pull requests, releases
– Transifex for community translations

##### Relationships and interactions
- Code Examples → CI → Pass/Fail status → Build approval
- GitHub (Repo) ← push (branches/tags) → triggers CI → artifacts deployed to Releases/Pages
- Translations (external) feed into content source via Pull Requests

##### Architectural patterns and design principles
- Separation of concerns: content vs. presentation (themes) vs. examples vs. build logic
- Extensibility: add new formats by dropping a new theme; add languages via code/ folder
- Reproducibility: CI ensures every commit can generate the same outputs
- Modularity: each chapter is an independent AsciiDoc file, appendices separate

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Commit to Repo triggers CI and Build
    Commit["Commit/Pull Request"]:::process -->|triggers| CI

    subgraph "Content Source" 
        direction TB
        Book["book.asciidoc"]:::repo
        Chapters["ch01.asciidoc … ch12.asciidoc"]:::repo
        Appendices["appdx-*.asciidoc"]:::repo
        FrontMatter["author_bio.html, preface.asciidoc, glossary.asciidoc, ..."]:::repo
        Images["images/"]:::repo
    end

    subgraph "Code Examples"
        direction TB
        CE1["addr.cpp"]:::repo
        CE2["bip-table.py"]:::repo
        CE3["ec-math.py"]:::repo
        CE4["extract-from-pk-script.go"]:::repo
        CE5["p2wpkh.js"]:::repo
    end

    subgraph "Theme / Presentation" 
        direction TB
        EPUB_CSS["theme/epub/epub.css"]:::repo
        EPUB_HTML["theme/epub/layout.html"]:::repo
        MOBI_CSS["theme/mobi/mobi.css"]:::repo
        MOBI_HTML["theme/mobi/layout.html"]:::repo
        PDF_CSS["theme/pdf/pdf.css"]:::repo
    end

    subgraph "Build Toolchain" 
        direction TB
        Asciidoctor["AsciiDoctor/Antora"]:::process
        Atlas["atlas.json"]:::repo
        Tools["tools/"]:::repo
    end

    subgraph "Continuous Integration" 
        direction TB
        Travis[".travis.yml"]:::repo
    end

    subgraph "Output Artifacts" 
        direction TB
        HTML["HTML Site"]:::output
        PDF["PDF"]:::output
        EPUB["EPUB"]:::output
        MOBI["MOBI"]:::output
        Releases["GitHub Releases"]:::output
    end

    subgraph "Repo Metadata" 
        direction TB
        Readme["README.md"]:::repo
        License["LICENSE"]:::repo
        GitAttr[".gitattributes"]:::repo
        GitIgnore[".gitignore"]:::repo
    end

    subgraph "External Services"
        direction TB
        GitHub["GitHub"]:::external
        Transifex["Transifex"]:::external
    end

    %% Relationships
    Book & Chapters & Appendices & FrontMatter & Images & EPUB_CSS & MOBI_CSS & PDF_CSS -->|inputs| Asciidoctor
    Asciidoctor & Tools -->|build| HTML & PDF & EPUB & MOBI
    CE1 & CE2 & CE3 & CE4 & CE5 -->|run tests| Travis
    Commit -->|push| GitHub
    GitHub -->|webhook| CI
    CI -->|run builds/tests| Travis & Asciidoctor
    HTML -->|deploy| GitHub
    Releases -->|tag/releases| GitHub
    Transifex -->|provide translations| GitHub

    %% Click Events Content Source
    click Book "https://github.com/eliblurr/bitcoinbook/blob/develop/book.asciidoc"
    click Chapters "https://github.com/eliblurr/bitcoinbook/blob/develop/ch01.asciidoc"
    click Appendices "https://github.com/eliblurr/bitcoinbook/blob/develop/appdx-bips.asciidoc"
    click FrontMatter "https://github.com/eliblurr/bitcoinbook/blob/develop/preface.asciidoc"
    click Images "https://github.com/eliblurr/bitcoinbook/tree/develop/images/"

    %% Click Events Code Examples
    click CE1 "https://github.com/eliblurr/bitcoinbook/blob/develop/code/addr.cpp"
    click CE2 "https://github.com/eliblurr/bitcoinbook/blob/develop/code/bip-table.py"
    click CE3 "https://github.com/eliblurr/bitcoinbook/blob/develop/code/ec-math.py"
    click CE4 "https://github.com/eliblurr/bitcoinbook/blob/develop/code/extract-from-pk-script.go"
    click CE5 "https://github.com/eliblurr/bitcoinbook/blob/develop/code/p2wpkh.js"

    %% Click Events Theme
    click EPUB_CSS "https://github.com/eliblurr/bitcoinbook/blob/develop/theme/epub/epub.css"
    click EPUB_HTML "https://github.com/eliblurr/bitcoinbook/blob/develop/theme/epub/layout.html"
    click MOBI_CSS "https://github.com/eliblurr/bitcoinbook/blob/develop/theme/mobi/mobi.css"
    click MOBI_HTML "https://github.com/eliblurr/bitcoinbook/blob/develop/theme/mobi/layout.html"
    click PDF_CSS "https://github.com/eliblurr/bitcoinbook/blob/develop/theme/pdf/pdf.css"

    %% Click Events Build Toolchain
    click Atlas "https://github.com/eliblurr/bitcoinbook/blob/develop/atlas.json"
    click Tools "https://github.com/eliblurr/bitcoinbook/tree/develop/tools/"

    %% Click Events CI
    click Travis "https://github.com/eliblurr/bitcoinbook/blob/develop/.travis.yml"

    %% Click Events Repo Metadata
    click Readme "https://github.com/eliblurr/bitcoinbook/blob/develop/README.md"
    click License "https://github.com/eliblurr/bitcoinbook/tree/develop/LICENSE"
    click GitAttr "https://github.com/eliblurr/bitcoinbook/blob/develop/.gitattributes"
    click GitIgnore "https://github.com/eliblurr/bitcoinbook/blob/develop/.gitignore"

    %% Styles
    classDef repo fill:#D0E6FF,stroke:#0366d6;
    classDef process fill:#DFFFE0,stroke:#28a745;
    classDef output fill:#FFF5CC,stroke:#DB8E00;
    classDef external fill:#E0E0E0,stroke:#888888;
    classDef process fill:#E8F4FF,stroke:#0366d6;
    class Commit,CI,Github,Transifex process;
    class Asciidoctor,Travis process;
    class GitHub,Transifex external;
```
