# magicbookproject/magicbook architecture

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

- Interactive diagram: https://gitdiagram.com/magicbookproject/magicbook
- Repository: https://github.com/magicbookproject/magicbook

## Overview

##### Major Components
- Command-Line Interface (CLI) – The entry point (src/index.js and src/new.js) that accepts commands (e.g., “magicbook build”, “magicbook new”) and command-line options.
- Configuration Manager – A component responsible for reading and processing “magicbook.json” (or custom config via --config) to determine settings such as file globs, build formats, destination folders, assets options, and plugin configurations.
- File Loader & Parser – This subsystem handles reading the source files (Markdown, HTML, images, fonts, etc.) from directories like “example/content” and “spec/support/book/content”. It also parses YAML frontmatter, Markdown conversion (to HTMLBook format), and initial processing of includes.
- Plugin Engine – The core plugin executer (see “src/plugin_executer.js” and the “src/plugins” folder) that registers, orders, and executes a series of plugins. These plugins add functionality for processing themes, footnotes, layouts, image transfers, digesting assets, and more.
- Build Pipeline – Manages the sequence of steps:
- Transforming and merging content,
- Inserting liquid variables (for TOC, navigation, etc.),
- Applying layouts and includes,
- Bundling assets, and
- Generating final outputs (HTML builds per file and combined PDF builds).
- Asset Manager – Specifically handles assets (images, fonts, stylesheets, javascripts) by copying (or transforming) them into destination folders as specified in the configuration, including options to compress, bundle and add digest checksums.
- Output Writer – Writes out the processed files to the build destination folders (e.g., “build/build1” or custom paths) for each build format.
- Testing Module – Although not part of the production build, directories like “spec” map to unit/integration tests that verify plugins and build behavior.

- The CLI triggers the Configuration Manager that reads “magicbook.json” to set the build parameters.
- The File Loader scans the designated folders (e.g., content, images, fonts, includes) and hands off the raw data to the Parser.
- The Parser processes the raw text (Markdown conversion, YAML frontmatter extraction) and passes the structured content to the Plugin Engine.
- The Plugin Engine (with its ordered plugins) manipulates the content and metadata; each plugin (like frontmatter, liquid templating, TOC generation, footnotes, asset processing) represents discrete steps in the build process.
- Processed content is then passed through the Build Pipeline where conditions for different formats (HTML vs. PDF) are handled – applying layouts, bundling assets, and re-adjusting links or file paths.
- The Asset Manager works in parallel within the build pipeline to handle fonts, images, stylesheets, and javascripts, ensuring they are relocated to proper output directories (with digest, compression, and bundling applied as configured).
- Finally, the Output Writer generates the final build output (static pages, single HTML for PDF conversion using Prince XML, etc.) which is dropped into the destination directory.
- External libraries (e.g., “sharp” for image processing or Prince XML for PDF generation) should be depicted as supporting third-party service components integrated in the respective steps.

##### Architectural Patterns & Design Principles
- Modular Plugin Architecture – Emphasize that most functionality is implemented as plugins. Represent the Plugin Engine as a central orchestrator where plugins are dynamically registered and executed.
- Layered Design – The build process is layered: configuration and file ingestion → processing (through plugins) → asset management → output generation.
- Extensibility – The configuration (JSON) and plugin support show that the system is built to be flexible and easily extended or modified.

##### Relevant Technologies and Components
- Node.js and the module-based implementation (with “src” for core logic, “spec” for tests).
- Liquid Templating – Used for layout processing, includes, and dynamic asset injection.
- Markdown Conversion (and HTMLBook standard) – For converting plain-text book content to structured HTML.
- Prince XML – Used for generating high-quality, print-ready PDFs (as noted in the README).
- SCSS/CSS and UglifyJS – For asset compilation, compression, and bundling in stylesheets and javascripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User("User CLI Command"):::external
    CLI("Command-Line Interface"):::core
    Config("Configuration Manager"):::core
    Loader("File Loader & Parser"):::core
    PluginEng("Plugin Engine"):::core
    BuildPipe("Build Pipeline"):::core
    AssetMan("Asset Manager"):::core
    Output("Output Writer"):::core
    TestMod("Testing Module"):::test
    Sharp("Sharp (Image Processing)"):::external
    Prince("PrinceXML (PDF Generation)"):::external

    User -->|"invokes"| CLI
    CLI -->|"triggers"| Config
    Config -->|"reads_config"| Loader
    Loader -->|"provides_raw_content"| PluginEng
    PluginEng -->|"applies_plugins"| BuildPipe
    AssetMan -->|"process_assets"| BuildPipe
    BuildPipe -->|"generates_final_output"| Output
    AssetMan -->|"handles_images"| Sharp
    Output -->|"pdf_generation"| Prince
    PluginEng ---|"tested_by"| TestMod

    subgraph "Asset Plugins"
        Img("Image Plugin"):::plugin
        Font("Font Plugin"):::plugin
        JS("Javascript Plugin"):::plugin
        CSS("Stylesheet Plugin"):::plugin
    end

    PluginEng -->|"includes"| Img
    PluginEng -->|"includes"| Font
    PluginEng -->|"includes"| JS
    PluginEng -->|"includes"| CSS

    %% Click Events for Command-Line Interface
    click CLI "https://github.com/magicbookproject/magicbook/blob/main/src/index.js"
    click CLI "https://github.com/magicbookproject/magicbook/blob/main/src/new.js"

    %% Click Events for Configuration Manager
    click Config "https://github.com/magicbookproject/magicbook/blob/main/example/magicbook.json"

    %% Click Events for File Loader & Parser
    click Loader "https://github.com/magicbookproject/magicbook/blob/main/src/helpers/file.js"
    click Loader "https://github.com/magicbookproject/magicbook/blob/main/src/helpers/htmlbook.js"
    %% Content directories (represented via Loader)
    click Loader "https://github.com/magicbookproject/magicbook/tree/main/example/content"
    click Loader "https://github.com/magicbookproject/magicbook/tree/main/spec/support/book/content"

    %% Click Events for Plugin Engine and its directory
    click PluginEng "https://github.com/magicbookproject/magicbook/blob/main/src/plugin_executer.js"
    click PluginEng "https://github.com/magicbookproject/magicbook/tree/main/src/plugins"

    %% Click Events for Asset Plugins
    click Img "https://github.com/magicbookproject/magicbook/blob/main/src/plugins/images.js"
    click Font "https://github.com/magicbookproject/magicbook/blob/main/src/plugins/fonts.js"
    click JS "https://github.com/magicbookproject/magicbook/blob/main/src/plugins/javascripts.js"
    click CSS "https://github.com/magicbookproject/magicbook/blob/main/src/plugins/stylesheets.js"
    %% Asset directories
    click AssetMan "https://github.com/magicbookproject/magicbook/tree/main/example/images"
    click AssetMan "https://github.com/magicbookproject/magicbook/tree/main/example/fonts"
    click AssetMan "https://github.com/magicbookproject/magicbook/tree/main/example/javascripts"
    click AssetMan "https://github.com/magicbookproject/magicbook/tree/main/example/stylesheets"

    %% Click Events for Build Pipeline
    click BuildPipe "https://github.com/magicbookproject/magicbook/blob/main/src/build.js"

    %% Click Events for Output Writer layouts
    click Output "https://github.com/magicbookproject/magicbook/blob/main/example/layouts/html.html"
    click Output "https://github.com/magicbookproject/magicbook/blob/main/example/layouts/pdf.html"

    %% Click Event for Testing Module
    click TestMod "https://github.com/magicbookproject/magicbook/tree/main/spec"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef plugin fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
