# vjgit-369/mastering-playwright-automation architecture

> Architecture diagram of the GitHub repository vjgit-369/mastering-playwright-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vjgit-369/mastering-playwright-automation
- Repository: https://github.com/vjgit-369/mastering-playwright-automation

## Overview

#### Purpose and Entry Points
This is a production publishing repository for *Mastering Playwright Automation*, not a Playwright application. It maintains the book source and compiles distributable DOCX, PDF/paperback, EPUB, and Kindle EPUB artifacts. Primary build entry points are `scripts/build-book.ps1`, `scripts/build-book.bat`, and `scripts/build-manuscript.js`; final KDP deliverables reside in `release/amazon-kdp/`.

#### Canonical Content Assembly
The canonical editorial source is Markdown, split into frontmatter, ordered chapters, appendix, and backmatter. Ordering and compilation intent are centralized outside the manuscript rather than inferred solely from filenames.
- `manuscript/frontmatter/`
- `manuscript/chapters/chapter-01.md`
- `publishing/book-order.txt`

`publishing/book-metadata.yaml` supplies publication metadata across output formats.

#### Compiler Orchestration
The Node.js compiler is the central control boundary. `scripts/compiler/build.js` coordinates reading source, merging it into a book representation, QA, and format-specific generators. `scripts/compiler/book-reader.js` and `scripts/compiler/manuscript-merger.js` form the source-to-composite-manuscript stage.
- `scripts/compiler/build.js`
- `scripts/compiler/book-reader.js`
- `scripts/compiler/manuscript-merger.js`

#### Content Quality Gates
Two QA layers validate the source/manuscript before or during rendering: general content checks and manuscript-specific checks; file validation protects expected inputs/outputs. These are internal build gates rather than runtime services.
- `scripts/compiler/content-qa.js`
- `scripts/compiler/manuscript-qa.js`
- `scripts/compiler/file-validator.js`

#### Format Rendering Pipelines
Format generators consume the assembled manuscript and emit publication artifacts. DOCX has both document and template generation; EPUB and Kindle are separate targets; PDF supports both a general generator and a 7x10 paperback-specific generator.
- `scripts/compiler/docx-generator.js`
- `scripts/compiler/epub-generator.js`
- `scripts/compiler/kindle-generator.js`
- `scripts/compiler/pdf-generator-7x10.js`

EPUB output is validated with the bundled Java-based EPUBCheck distribution through `scripts/compiler/validate-epub.js` and `tools/epubcheck/epubcheck.jar`.

#### Presentation and Asset Boundary
Markdown structure is transformed by Lua filters, while TeX themes/templates define PDF and paperback visual design. This separates editorial content from output-specific layout. Reusable source diagrams are Draw.io files, with exported artwork available for rendering.
- `scripts/filters/paperback-structure.lua`
- `publishing/paperback/paperback-template-7x10.tex`
- `publishing/paperback/theme-7x10/theme-7x10.tex`
- `assets/diagrams/`

#### Publishing and Release
Publishing metadata, KDP copy, cover specifications, and marketing material are maintained as release-adjacent inputs. The release directory contains generated, upload-ready Amazon KDP files, including paperback PDF, cover PDF, DOCX, EPUB, and Kindle EPUB.
- `publishing/KDP_METADATA.md`
- `publishing/cover/cover-spec.md`
- `release/amazon-kdp/`

Material runtimes are Node.js for compilation, TeX/PDF tooling for print production, Lua/Pandoc-style filters, and Java for EPUBCheck. The only explicit external distribution target is Amazon KDP; no hosted application or backend service is present.

Main entry points: [`scripts/compiler/build.js`](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/build.js) (Compiler orchestrator), [`scripts/compiler/book-reader.js`](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/book-reader.js) (Book reader), [`scripts/compiler/pdf-generator-7x10.js`](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/pdf-generator-7x10.js) (7x10 PDF generator), [`scripts/compiler/validate-epub.js`](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/validate-epub.js) (EPUB validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Editorial Source"]
  node_content["Markdown manuscript<br/>content"]
  node_chapter["Chapter source<br/>markdown<br/>[chapter-01.md]"]
  node_book_order["Book order<br/>manifest<br/>[book-order.txt]"]
  node_metadata["Book metadata<br/>[book-metadata.yaml]"]
  node_diagrams["Diagram assets<br/>Draw.io artwork"]
end

subgraph group_compiler["Build Compiler"]
  node_entrypoints["Build entry points<br/>scripts<br/>[build-book.ps1]"]
  node_build{{"Compiler orchestrator<br/>Node.js compiler<br/>[build.js]"}}
  node_reader["Book reader<br/>compiler stage<br/>[book-reader.js]"]
  node_merger["Manuscript merger<br/>compiler stage"]
  node_qa["Content QA gates<br/>validation<br/>[content-qa.js]"]
  node_file_validation["File validation<br/>[file-validator.js]"]
end

subgraph group_render["Rendering &amp; Validation"]
  node_docx["DOCX generator<br/>renderer<br/>[docx-generator.js]"]
  node_epub["EPUB generator<br/>renderer<br/>[epub-generator.js]"]
  node_kindle["Kindle generator<br/>renderer"]
  node_paperback_pdf["7x10 PDF generator<br/>print renderer"]
  node_epub_validation["EPUB validation<br/>Java validation<br/>[validate-epub.js]"]
  node_epubcheck["EPUBCheck<br/>Java tool<br/>[epubcheck.jar]"]
  node_print_layout["Paperback layout<br/>Lua and TeX"]
end

subgraph group_release["Release Inputs &amp; Delivery"]
  node_release_inputs["KDP release inputs<br/>publishing assets<br/>[KDP_METADATA.md]"]
  node_kdp_release["Amazon KDP deliverables<br/>distribution artifacts"]
end

node_entrypoints -->|"invokes"| node_build
node_content -->|"reads"| node_reader
node_chapter -->|"reads"| node_reader
node_book_order -->|"orders"| node_reader
node_metadata -->|"supplies metadata"| node_build
node_reader -->|"source sections"| node_merger
node_merger -->|"composite manuscript"| node_qa
node_build -->|"checks files"| node_file_validation
node_qa -->|"quality gate"| node_build
node_file_validation -->|"validation gate"| node_build
node_build -->|"renders"| node_docx
node_build -->|"renders"| node_epub
node_build -->|"renders"| node_kindle
node_build -->|"renders"| node_paperback_pdf
node_diagrams -->|"artwork input"| node_build
node_print_layout -->|"applies layout"| node_paperback_pdf
node_epub -->|"validates"| node_epub_validation
node_epubcheck -->|"executes"| node_epub_validation
node_release_inputs -->|"release context"| node_kdp_release
node_docx -->|"publishes"| node_kdp_release
node_epub_validation -->|"approved EPUB"| node_kdp_release
node_kindle -->|"publishes"| node_kdp_release
node_paperback_pdf -->|"publishes"| node_kdp_release

click node_entrypoints "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/build-book.ps1"
click node_chapter "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/manuscript/chapters/chapter-01.md"
click node_book_order "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/publishing/book-order.txt"
click node_metadata "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/publishing/book-metadata.yaml"
click node_build "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/build.js"
click node_reader "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/book-reader.js"
click node_merger "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/manuscript-merger.js"
click node_qa "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/content-qa.js"
click node_file_validation "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/file-validator.js"
click node_docx "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/docx-generator.js"
click node_epub "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/epub-generator.js"
click node_kindle "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/kindle-generator.js"
click node_paperback_pdf "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/pdf-generator-7x10.js"
click node_epub_validation "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/validate-epub.js"
click node_epubcheck "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/tools/epubcheck/epubcheck.jar"
click node_print_layout "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/filters/paperback-structure.lua"
click node_release_inputs "https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/publishing/KDP_METADATA.md"

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_content,node_chapter,node_book_order,node_metadata,node_diagrams toneBlue
class node_entrypoints,node_build,node_reader,node_merger,node_qa,node_file_validation toneAmber
class node_docx,node_epub,node_kindle,node_paperback_pdf,node_epub_validation,node_epubcheck,node_print_layout toneMint
class node_release_inputs,node_kdp_release toneRose
```

## Components

### Editorial Source

- **Markdown manuscript**: content · Frontmatter, ordered chapters, appendix, and backmatter.
- [Chapter source](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/manuscript/chapters/chapter-01.md): markdown · `manuscript/chapters/chapter-01.md`
- [Book order](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/publishing/book-order.txt): manifest · Defines compilation order independently of filenames. · `publishing/book-order.txt`
- [Book metadata](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/publishing/book-metadata.yaml): metadata · Shared publication metadata for output formats. · `publishing/book-metadata.yaml`
- **Diagram assets**: Draw.io artwork · Reusable source diagrams and exported art.

### Build Compiler

- [Build entry points](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/build-book.ps1): scripts · PowerShell, batch, and Node build commands. · `scripts/build-book.ps1`
- [Compiler orchestrator](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/build.js): Node.js compiler · Coordinates assembly, QA, and generators. · `scripts/compiler/build.js`
- [Book reader](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/book-reader.js): compiler stage · `scripts/compiler/book-reader.js`
- [Manuscript merger](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/manuscript-merger.js): compiler stage · Builds the composite manuscript. · `scripts/compiler/manuscript-merger.js`
- [Content QA gates](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/content-qa.js): validation · General and manuscript-specific source checks. · `scripts/compiler/content-qa.js`
- [File validation](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/file-validator.js): validation · Protects required build inputs and outputs. · `scripts/compiler/file-validator.js`

### Rendering & Validation

- [DOCX generator](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/docx-generator.js): renderer · Produces document and template output. · `scripts/compiler/docx-generator.js`
- [EPUB generator](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/epub-generator.js): renderer · `scripts/compiler/epub-generator.js`
- [Kindle generator](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/kindle-generator.js): renderer · `scripts/compiler/kindle-generator.js`
- [7x10 PDF generator](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/pdf-generator-7x10.js): print renderer · Produces paperback-specific PDF. · `scripts/compiler/pdf-generator-7x10.js`
- [EPUB validation](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/compiler/validate-epub.js): Java validation · Runs bundled EPUBCheck against EPUB output. · `scripts/compiler/validate-epub.js`
- [EPUBCheck](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/tools/epubcheck/epubcheck.jar): Java tool · `tools/epubcheck/epubcheck.jar`
- [Paperback layout](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/scripts/filters/paperback-structure.lua): Lua and TeX · Filters and TeX themes separate print design from editorial content. · `scripts/filters/paperback-structure.lua`

### Release Inputs & Delivery

- [KDP release inputs](https://github.com/vjgit-369/mastering-playwright-automation/blob/publishing/publishing/KDP_METADATA.md): publishing assets · KDP copy, cover specifications, and marketing inputs. · `publishing/KDP_METADATA.md`
- **Amazon KDP deliverables**: distribution artifacts · Upload-ready paperback, cover, DOCX, EPUB, and Kindle EPUB files.

## Connections

- Build entry points → Compiler orchestrator: invokes
- Markdown manuscript → Book reader: reads
- Chapter source → Book reader: reads
- Book order → Book reader: orders
- Book metadata → Compiler orchestrator: supplies metadata
- Book reader → Manuscript merger: source sections
- Manuscript merger → Content QA gates: composite manuscript
- Compiler orchestrator → File validation: checks files
- Content QA gates → Compiler orchestrator: quality gate
- File validation → Compiler orchestrator: validation gate
- Compiler orchestrator → DOCX generator: renders
- Compiler orchestrator → EPUB generator: renders
- Compiler orchestrator → Kindle generator: renders
- Compiler orchestrator → 7x10 PDF generator: renders
- Diagram assets → Compiler orchestrator: artwork input
- Paperback layout → 7x10 PDF generator: applies layout
- EPUB generator → EPUB validation: validates
- EPUBCheck → EPUB validation: executes
- KDP release inputs → Amazon KDP deliverables: release context
- DOCX generator → Amazon KDP deliverables: publishes
- EPUB validation → Amazon KDP deliverables: approved EPUB
- Kindle generator → Amazon KDP deliverables: publishes
- 7x10 PDF generator → Amazon KDP deliverables: publishes