# oleksiy-nesterov/publication-builder architecture

> Architecture diagram of the GitHub repository oleksiy-nesterov/publication-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oleksiy-nesterov/publication-builder
- Repository: https://github.com/oleksiy-nesterov/publication-builder

## Overview

Publication Builder turns a publication folder of HTML/Nunjucks pages, CSS, templates, and assets into web output or PDFs, with a live-preview route for authoring. The build entry point loads publication metadata, renders pages and styles, resolves assets, then writes web output or invokes Vivliostyle for PDF targets. The README documents fixed-page catalogues, automatically paginated books, reusable templates, local data formats, print TIFF replacements, and CMYK processing; the graph preserves these capabilities while some implementation details remain unsampled.

Main entry points: [`src/api/buildApi.ts`](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/buildApi.ts) (Build orchestration), [`src/api/renderApi.ts`](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/renderApi.ts) (Publication rendering), [`src/api/devApi.ts`](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/devApi.ts) (Live preview), [`src/api/templateApi.ts`](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/templateApi.ts) (Template and file rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and preview"]
  node_build_cli["Build command<br/>[index.ts]"]
  node_preview_server["Live preview<br/>[devApi.ts]"]
end

subgraph group_content["Publication content"]
  node_publication_data["Publication metadata"]
  node_page_content["Pages and data"]
  node_shared_templates["Reusable templates"]
  node_design_assets["Styles and assets"]
end

subgraph group_render["Rendering"]
  node_publication_loader["Publication loader<br/>[publicationApi.ts]"]
  node_template_renderer["Template and file rendering<br/>[templateApi.ts]"]
  node_file_helpers["Local file helpers<br/>[fileApi.ts]"]
  node_asset_resolver["Asset resolution<br/>[assetResolver.ts]"]
  node_css_resolver["CSS collection<br/>[cssResolver.ts]"]
  node_publication_renderer["Publication rendering<br/>[renderApi.ts]"]
end

subgraph group_output["Build outputs"]
  node_build_pipeline["Build orchestration<br/>[buildApi.ts]"]
  node_web_output["Static web output"]
  node_pdf_output["PDF output"]
end

node_author(("Publication author"))
node_vivliostyle["Vivliostyle"]
node_preview_result(("Browser preview"))

node_author -->|"selects target"| node_build_cli
node_build_cli -->|"starts build"| node_build_pipeline
node_build_pipeline -->|"loads metadata"| node_publication_loader
node_publication_loader -->|"reads manifest"| node_publication_data
node_publication_loader -->|"validates pages"| node_page_content
node_build_pipeline -->|"renders publication"| node_publication_renderer
node_publication_renderer -->|"renders pages"| node_template_renderer
node_publication_renderer -->|"resolves assets"| node_asset_resolver
node_publication_renderer -->|"collects styles"| node_css_resolver
node_template_renderer -->|"resolves templates"| node_shared_templates
node_template_renderer -->|"provides file access"| node_file_helpers
node_template_renderer -->|"resolves local assets"| node_asset_resolver
node_css_resolver -->|"collects CSS"| node_design_assets
node_asset_resolver -->|"resolves publication assets"| node_design_assets
node_build_pipeline -->|"writes web build"| node_web_output
node_build_pipeline -->|"generates PDF"| node_vivliostyle
node_vivliostyle -->|"writes PDF"| node_pdf_output
node_author -->|"requests preview"| node_preview_server
node_preview_server -->|"loads publication"| node_publication_loader
node_preview_server -->|"renders request"| node_publication_renderer
node_preview_server -->|"serves pages"| node_preview_result
node_design_assets -->|"print TIFF substitution"| node_asset_resolver

click node_build_cli "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/index.ts"
click node_preview_server "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/devApi.ts"
click node_publication_data "https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications"
click node_page_content "https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications"
click node_shared_templates "https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications"
click node_design_assets "https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications"
click node_publication_loader "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/publicationApi.ts"
click node_template_renderer "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/templateApi.ts"
click node_file_helpers "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/fileApi.ts"
click node_asset_resolver "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/resolvers/assetResolver.ts"
click node_css_resolver "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/resolvers/cssResolver.ts"
click node_publication_renderer "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/renderApi.ts"
click node_build_pipeline "https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/buildApi.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_cli,node_preview_server,node_preview_result toneBlue
class node_publication_data,node_page_content,node_shared_templates,node_design_assets toneAmber
class node_publication_loader,node_template_renderer,node_file_helpers,node_asset_resolver,node_css_resolver,node_publication_renderer toneMint
class node_build_pipeline,node_web_output,node_pdf_output toneRose
class node_author,node_vivliostyle toneIndigo
```

## Components

### Entry and preview

- [Build command](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/index.ts): `src/index.ts`
- [Live preview](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/devApi.ts): `src/api/devApi.ts`

### Publication content

- [Publication metadata](https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications): `publications`
- [Pages and data](https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications): `publications`
- [Reusable templates](https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications): `publications`
- [Styles and assets](https://github.com/oleksiy-nesterov/publication-builder/tree/main/publications): `publications`

### Rendering

- [Publication loader](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/publicationApi.ts): `src/api/publicationApi.ts`
- [Template and file rendering](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/templateApi.ts): `src/api/templateApi.ts`
- [Local file helpers](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/fileApi.ts): `src/api/fileApi.ts`
- [Asset resolution](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/resolvers/assetResolver.ts): `src/resolvers/assetResolver.ts`
- [CSS collection](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/resolvers/cssResolver.ts): `src/resolvers/cssResolver.ts`
- [Publication rendering](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/renderApi.ts): `src/api/renderApi.ts`

### Build outputs

- [Build orchestration](https://github.com/oleksiy-nesterov/publication-builder/blob/main/src/api/buildApi.ts): `src/api/buildApi.ts`
- **Static web output**
- **PDF output**

### Other components

- **Publication author**
- **Vivliostyle**
- **Browser preview**

## Connections

- Publication author → Build command: selects target (evidence: `README.md`)
- Build command → Build orchestration: starts build (evidence: `src/index.ts`)
- Build orchestration → Publication loader: loads metadata (evidence: `src/api/buildApi.ts`)
- Publication loader → Publication metadata: reads manifest (evidence: `README.md`)
- Publication loader → Pages and data: validates pages (evidence: `src/api/publicationApi.ts`)
- Build orchestration → Publication rendering: renders publication (evidence: `src/api/buildApi.ts`)
- Publication rendering → Template and file rendering: renders pages (evidence: `src/api/renderApi.ts`)
- Publication rendering → Asset resolution: resolves assets (evidence: `src/api/renderApi.ts`)
- Publication rendering → CSS collection: collects styles (evidence: `src/api/renderApi.ts`)
- Template and file rendering → Reusable templates: resolves templates (evidence: `README.md`)
- Template and file rendering → Local file helpers: provides file access (evidence: `src/api/templateApi.ts`)
- Template and file rendering → Asset resolution: resolves local assets (evidence: `src/api/templateApi.ts`)
- CSS collection → Styles and assets: collects CSS (evidence: `src/resolvers/cssResolver.ts`)
- Asset resolution → Styles and assets: resolves publication assets (evidence: `README.md`)
- Build orchestration → Static web output: writes web build (evidence: `README.md`)
- Build orchestration → Vivliostyle: generates PDF (evidence: `README.md`)
- Vivliostyle → PDF output: writes PDF (evidence: `README.md`)
- Publication author → Live preview: requests preview (evidence: `README.md`)
- Live preview → Publication loader: loads publication (evidence: `src/api/devApi.ts`)
- Live preview → Publication rendering: renders request (evidence: `src/api/devApi.ts`)
- Live preview → Browser preview: serves pages (evidence: `src/api/devApi.ts`)
- Styles and assets → Asset resolution: print TIFF substitution (evidence: `README.md`)
