# pskumaresh06/wasmtex-playground architecture

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

- Interactive diagram: https://gitdiagram.com/pskumaresh06/wasmtex-playground
- Repository: https://github.com/pskumaresh06/wasmtex-playground

## Overview

#### Purpose and Entry Points
WASMTeX Playground is a browser-hosted LaTeX editor/compiler with PDF preview. The primary client entry is `index.html`, using the JavaScript compiler wrapper in `PdfTeXEngine.js`. Deployment starts through `docker-compose.yml`, which serves static browser assets and a separate TeXLive compilation service.

#### Browser Editor and Compile Orchestration
`index.html` owns the interactive UI: source editing, project/image upload, compile actions, console output, PDF preview/download, and default-asset status. It passes LaTeX source and uploaded files into the compiler-facing JavaScript layer.
- `index.html`
- `PdfTeXEngine.js`

#### In-Browser PdfTeX Runtime
The browser path uses a PdfTeX engine compiled to WebAssembly. The wrapper exposes compiler lifecycle and its in-memory filesystem to the UI; compilation consumes `.tex` plus assets and emits PDF bytes and logs. This is the key browser/runtime boundary: no browser filesystem access is assumed, so source, uploads, and bundled assets must be materialized in the engine’s virtual filesystem.
- `PdfTeXEngine.js`
- `wasm-builder/pdftex.wasm/PdfTeXEngine.js`
- `wasm-builder/pdftex.wasm/library.js`

#### Default Asset Layer
A repository-provided TeX asset corpus supplies document classes, packages, format files, fonts, maps, and graphics support. The client is designed to load these resources into compiler memory, allowing documents to resolve `\usepackage`, classes, and included resources without user upload. The asset boundary is filename/package resolution inside PdfTeX rather than application-level APIs.
- `default-assets/`
- `default-assets/neopdftex.fmt`
- `default-assets/article.cls`

#### Containerized Server Compilation
Docker Compose also provisions `texlive-ondemand`, a Python/Wsgi service on port 5002, alongside a static server on port 8002. This creates a second compilation boundary: browser UI/static delivery versus server-side TeXLive compilation. The service includes a precompiled format and custom kpathsea/PdfTeX integration for locating TeX resources.
- `docker-compose.yml`
- `texlive-ondemand/app.py`
- `texlive-ondemand/wsgi.py`

#### Native/Server PdfTeX Resource Resolution
The server compiler service is built around Python plus a native `pykpathsea_pdftex` implementation/setup, with a packaged `neopdftex.fmt`. It is responsible for invoking/configuring the TeX runtime and resolving TeX inputs in the service environment.
- `texlive-ondemand/kpathsea_pdftex_setup.py`
- `texlive-ondemand/pykpathsea_pdftex.c`
- `texlive-ondemand/neopdftex.fmt`

#### WASM Build Pipeline and Engine Sources
`wasm-builder/pdftex.wasm` contains the Emscripten build target, generated/runtime glue, PdfTeX sources, and embedded PDF-processing dependencies. Its Makefile produces the WebAssembly engine consumed by the frontend; rebuilding requires Emscripten SDK 3.1.46 per the README. Core engine execution enters through C glue and PdfTeX’s TeX implementation.
- `wasm-builder/pdftex.wasm/Makefile`
- `wasm-builder/pdftex.wasm/main.c`
- `wasm-builder/pdftex.wasm/tex/pdftex0.c`

#### Primary Flow
User edits/uploads → `index.html` selects a main `.tex` and gathers assets → default and user files are written to the compiler virtual filesystem → PdfTeX compiles against format/package resources → PDF bytes render in the preview and become downloadable; logs/errors return to the console UI. Docker adds static delivery and an optional/separate TeXLive-backed compiler endpoint, but the central product capability is the WebAssembly PdfTeX path.

Main entry points: [`PdfTeXEngine.js`](https://github.com/pskumaresh06/wasmtex-playground/blob/main/PdfTeXEngine.js) (Compiler Wrapper), [`texlive-ondemand/app.py`](https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/app.py) (TeXLive Service), [`wasm-builder/pdftex.wasm`](https://github.com/pskumaresh06/wasmtex-playground/tree/main/wasm-builder/pdftex.wasm) (PdfTeX WebAssembly), [`wasm-builder/pdftex.wasm/Makefile`](https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/Makefile) (WASM Build Target)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser Playground"]
  node_ui["Playground UI<br/>browser entry<br/>[index.html]"]
  node_wrapper["Compiler Wrapper<br/>JavaScript API<br/>[PdfTeXEngine.js]"]
end

subgraph group_wasm["WASM PdfTeX"]
  node_wasm_api["WASM Engine API<br/>runtime glue<br/>[PdfTeXEngine.js]"]
  node_wasm_glue["Emscripten Library<br/>runtime glue<br/>[library.js]"]
  node_pdftex_wasm{{"PdfTeX WebAssembly<br/>compiler runtime<br/>[pdftex.wasm]"}}
end

subgraph group_assets["TeX Assets"]
  node_default_assets[("Default Asset Corpus<br/>TeX resources")]
  node_browser_format["Browser Format<br/>PdfTeX format<br/>[neopdftex.fmt]"]
  node_article_class["Article Class<br/>TeX class<br/>[article.cls]"]
end

subgraph group_server["Server Compilation"]
  node_compose["Compose Deployment<br/>container orchestration<br/>[docker-compose.yml]"]
  node_static_server["Static Server<br/>asset delivery"]
  node_texlive_app["TeXLive Service<br/>Python/Wsgi compiler<br/>[app.py]"]
  node_wsgi["WSGI Entry<br/>service entry<br/>[wsgi.py]"]
  node_kpathsea_setup["Kpathsea Setup<br/>Python integration"]
  node_native_kpathsea{{"Native PdfTeX Resolver<br/>C extension"}}
  node_server_format["Server Format<br/>PdfTeX format<br/>[neopdftex.fmt]"]
end

subgraph group_build["WASM Build"]
  node_makefile["WASM Build Target<br/>Emscripten build<br/>[Makefile]"]
  node_c_glue["Compiler C Glue<br/>native entry<br/>[main.c]"]
  node_pdftex_core["PdfTeX Core<br/>TeX implementation<br/>[pdftex0.c]"]
end

node_compose -->|"starts"| node_static_server
node_compose -->|"starts"| node_texlive_app
node_static_server -->|"serves"| node_ui
node_ui -->|"source and uploads"| node_wrapper
node_wrapper -->|"controls"| node_wasm_api
node_wasm_api -->|"uses"| node_wasm_glue
node_wasm_glue -->|"loads"| node_pdftex_wasm
node_wrapper -->|"materializes in VFS"| node_default_assets
node_default_assets -->|"includes"| node_browser_format
node_default_assets -->|"includes"| node_article_class
node_wrapper -->|"writes VFS and compiles"| node_pdftex_wasm
node_pdftex_wasm -->|"PDF bytes and logs"| node_ui
node_wsgi -->|"hosts"| node_texlive_app
node_texlive_app -->|"configures"| node_kpathsea_setup
node_kpathsea_setup -->|"uses"| node_native_kpathsea
node_texlive_app -->|"loads"| node_server_format
node_makefile -->|"builds"| node_c_glue
node_makefile -->|"builds"| node_pdftex_core
node_makefile -->|"produces"| node_pdftex_wasm
node_c_glue -->|"enters"| node_pdftex_core

click node_ui "https://github.com/pskumaresh06/wasmtex-playground/blob/main/index.html"
click node_wrapper "https://github.com/pskumaresh06/wasmtex-playground/blob/main/PdfTeXEngine.js"
click node_wasm_api "https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/PdfTeXEngine.js"
click node_wasm_glue "https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/library.js"
click node_pdftex_wasm "https://github.com/pskumaresh06/wasmtex-playground/tree/main/wasm-builder/pdftex.wasm"
click node_browser_format "https://github.com/pskumaresh06/wasmtex-playground/blob/main/default-assets/neopdftex.fmt"
click node_article_class "https://github.com/pskumaresh06/wasmtex-playground/blob/main/default-assets/article.cls"
click node_compose "https://github.com/pskumaresh06/wasmtex-playground/blob/main/docker-compose.yml"
click node_texlive_app "https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/app.py"
click node_wsgi "https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/wsgi.py"
click node_kpathsea_setup "https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/kpathsea_pdftex_setup.py"
click node_native_kpathsea "https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/pykpathsea_pdftex.c"
click node_server_format "https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/neopdftex.fmt"
click node_makefile "https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/Makefile"
click node_c_glue "https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/main.c"
click node_pdftex_core "https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/tex/pdftex0.c"

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_ui,node_wrapper toneBlue
class node_wasm_api,node_wasm_glue,node_pdftex_wasm toneAmber
class node_default_assets,node_browser_format,node_article_class toneMint
class node_compose,node_static_server,node_texlive_app,node_wsgi,node_kpathsea_setup,node_native_kpathsea,node_server_format toneRose
class node_makefile,node_c_glue,node_pdftex_core toneIndigo
```

## Components

### Browser Playground

- [Playground UI](https://github.com/pskumaresh06/wasmtex-playground/blob/main/index.html): browser entry · Edits sources, accepts uploads, and shows output. · `index.html`
- [Compiler Wrapper](https://github.com/pskumaresh06/wasmtex-playground/blob/main/PdfTeXEngine.js): JavaScript API · Manages compiler lifecycle and virtual files. · `PdfTeXEngine.js`

### WASM PdfTeX

- [WASM Engine API](https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/PdfTeXEngine.js): runtime glue · `wasm-builder/pdftex.wasm/PdfTeXEngine.js`
- [Emscripten Library](https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/library.js): runtime glue · `wasm-builder/pdftex.wasm/library.js`
- [PdfTeX WebAssembly](https://github.com/pskumaresh06/wasmtex-playground/tree/main/wasm-builder/pdftex.wasm): compiler runtime · Compiles virtual .tex files and returns PDF bytes and logs. · `wasm-builder/pdftex.wasm`

### TeX Assets

- **Default Asset Corpus**: TeX resources · Classes, packages, fonts, maps, and graphics support.
- [Browser Format](https://github.com/pskumaresh06/wasmtex-playground/blob/main/default-assets/neopdftex.fmt): PdfTeX format · `default-assets/neopdftex.fmt`
- [Article Class](https://github.com/pskumaresh06/wasmtex-playground/blob/main/default-assets/article.cls): TeX class · `default-assets/article.cls`

### Server Compilation

- [Compose Deployment](https://github.com/pskumaresh06/wasmtex-playground/blob/main/docker-compose.yml): container orchestration · Starts static delivery and the optional compiler service. · `docker-compose.yml`
- **Static Server**: asset delivery · Serves browser assets on port 8002.
- [TeXLive Service](https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/app.py): Python/Wsgi compiler · Provides server-side compilation on port 5002. · `texlive-ondemand/app.py`
- [WSGI Entry](https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/wsgi.py): service entry · `texlive-ondemand/wsgi.py`
- [Kpathsea Setup](https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/kpathsea_pdftex_setup.py): Python integration · Configures TeX input resolution. · `texlive-ondemand/kpathsea_pdftex_setup.py`
- [Native PdfTeX Resolver](https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/pykpathsea_pdftex.c): C extension · `texlive-ondemand/pykpathsea_pdftex.c`
- [Server Format](https://github.com/pskumaresh06/wasmtex-playground/blob/main/texlive-ondemand/neopdftex.fmt): PdfTeX format · `texlive-ondemand/neopdftex.fmt`

### WASM Build

- [WASM Build Target](https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/Makefile): Emscripten build · Builds the browser compiler runtime. · `wasm-builder/pdftex.wasm/Makefile`
- [Compiler C Glue](https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/main.c): native entry · `wasm-builder/pdftex.wasm/main.c`
- [PdfTeX Core](https://github.com/pskumaresh06/wasmtex-playground/blob/main/wasm-builder/pdftex.wasm/tex/pdftex0.c): TeX implementation · `wasm-builder/pdftex.wasm/tex/pdftex0.c`

## Connections

- Compose Deployment → Static Server: starts
- Compose Deployment → TeXLive Service: starts
- Static Server → Playground UI: serves
- Playground UI → Compiler Wrapper: source and uploads
- Compiler Wrapper → WASM Engine API: controls
- WASM Engine API → Emscripten Library: uses
- Emscripten Library → PdfTeX WebAssembly: loads
- Compiler Wrapper → Default Asset Corpus: materializes in VFS
- Default Asset Corpus → Browser Format: includes
- Default Asset Corpus → Article Class: includes
- Compiler Wrapper → PdfTeX WebAssembly: writes VFS and compiles
- PdfTeX WebAssembly → Playground UI: PDF bytes and logs
- WSGI Entry → TeXLive Service: hosts
- TeXLive Service → Kpathsea Setup: configures
- Kpathsea Setup → Native PdfTeX Resolver: uses
- TeXLive Service → Server Format: loads
- WASM Build Target → Compiler C Glue: builds
- WASM Build Target → PdfTeX Core: builds
- WASM Build Target → PdfTeX WebAssembly: produces
- Compiler C Glue → PdfTeX Core: enters