# swiftlatex/texlive-ondemand architecture

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

- Interactive diagram: https://gitdiagram.com/swiftlatex/texlive-ondemand
- Repository: https://github.com/swiftlatex/texlive-ondemand

## Overview

##### Project type and purpose
- This is a single-service, backend‐only application implemented in Python.
- Purpose: serve TeX Live files (formats, fonts, macro packages, etc.) on demand over HTTP so TeX engines (pdftex, xetex) can fetch needed resources lazily instead of bundling a full local TeX Live tree.

##### File structure
- Top-level scripts and config:
- Dockerfile, docker-compose.yml: containerized deployment
- app.py, wsgi.py: Python WSGI web application
- requirements.txt: Python dependencies
- kpathsea_*.py, pykpathsea_*.c: custom path‐resolution modules binding to kpathsea C library
- .fmt and .txt files: prebuilt TeX format files and font listings served to clients
- sign.bat: Windows helper, not in main request path
- No separate “frontend” or databases—pure HTTP file‐server logic wrapping kpathsea lookups.

##### README for additional insights
- Confirms the goal is “Serving TexLive Files in an On-Demand Manner.”

##### Final advice
- Every single moving part: C-extensions, format files, Docker layers.
- Keep labels precise (“HTTP GET /fonts/cm-unicode.ttf”) to show real endpoints.
- Use consistent iconography: containers, servers, libraries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["TeX Engine Client\n(pdftex/xetex)"]:::external

    %% Reverse Proxy
    Proxy["Reverse Proxy\n(Nginx/Traefik)"]:::proxy

    %% WSGI Server
    WSGI["WSGI Server\n(gunicorn/uwsgi)"]:::server

    %% Python Application
    App["Python Application\n(app.py, wsgi.py)"]:::app

    %% kpathsea setup modules
    subgraph "kpathsea Setup Modules"
        direction TB
        KPDF["kpathsea_pdftex_setup.py"]:::module
        KXET["kpathsea_xetex_setup.py"]:::module
    end

    %% pykpathsea C extensions
    subgraph "pykpathsea C Extensions"
        direction TB
        Cpdf["pykpathsea_pdftex.c"]:::cext
        Cxet["pykpathsea_xetex.c"]:::cext
    end

    %% File Store
    subgraph "TeX Live File Store"
        direction TB
        Format1["swiftlatexpdftex.fmt"]:::asset
        Format2["swiftlatexxetex.fmt"]:::asset
        FontList["xetexfontlist.txt"]:::asset
    end

    %% Docker Host & Config
    subgraph "Docker Host" 
        direction TB
        Dockerfile["Dockerfile"]:::config
        Compose["docker-compose.yml"]:::config
        Requirements["requirements.txt"]:::config
        Sign["sign.bat"]:::config
        Cert["app.cer"]:::config
    end

    %% Connections
    Client -->|HTTP GET| Proxy
    Proxy -->|Forward HTTP| WSGI
    WSGI -->|Invoke app| App
    App -->|import/setup| KPDF
    App -->|import/setup| KXET
    App -->|call extension| Cpdf
    App -->|call extension| Cxet
    Cpdf -->|file lookup| Format1
    Cpdf -->|file lookup| Format2
    Cxet -->|file lookup| FontList
    App -->|read file I/O| Format1
    App -->|read file I/O| Format2
    App -->|read file I/O| FontList
    Dockerfile --> DockerHost
    Compose --> DockerHost
    Requirements --> App
    Cert --> Proxy
    Sign --> DockerHost

    %% Click Events
    click Dockerfile "https://github.com/swiftlatex/texlive-ondemand/tree/master/Dockerfile"
    click Compose "https://github.com/swiftlatex/texlive-ondemand/blob/master/docker-compose.yml"
    click Requirements "https://github.com/swiftlatex/texlive-ondemand/blob/master/requirements.txt"
    click App "https://github.com/swiftlatex/texlive-ondemand/blob/master/app.py"
    click WSGI "https://github.com/swiftlatex/texlive-ondemand/blob/master/wsgi.py"
    click KPDF "https://github.com/swiftlatex/texlive-ondemand/blob/master/kpathsea_pdftex_setup.py"
    click KXET "https://github.com/swiftlatex/texlive-ondemand/blob/master/kpathsea_xetex_setup.py"
    click Cpdf "https://github.com/swiftlatex/texlive-ondemand/blob/master/pykpathsea_pdftex.c"
    click Cxet "https://github.com/swiftlatex/texlive-ondemand/blob/master/pykpathsea_xetex.c"
    click Format1 "https://github.com/swiftlatex/texlive-ondemand/blob/master/swiftlatexpdftex.fmt"
    click Format2 "https://github.com/swiftlatex/texlive-ondemand/blob/master/swiftlatexxetex.fmt"
    click FontList "https://github.com/swiftlatex/texlive-ondemand/blob/master/xetexfontlist.txt"
    click Sign "https://github.com/swiftlatex/texlive-ondemand/blob/master/sign.bat"
    click Cert "https://github.com/swiftlatex/texlive-ondemand/blob/master/app.cer"

    %% Styles
    classDef external fill:#a2d5f2,stroke:#084c61,color:#084c61
    classDef proxy fill:#ffcb77,stroke:#b56576,color:#b56576
    classDef server fill:#d4f1f4,stroke:#05668d,color:#05668d
    classDef app fill:#bde0fe,stroke:#1d3557,color:#1d3557
    classDef module fill:#f0efeb,stroke:#333,color:#333
    classDef cext fill:#ffe8d6,stroke:#cb997e,color:#cb997e
    classDef storage fill:#e4c1f4,stroke:#9d4edd,color:#9d4edd
    classDef container fill:#c0fdfb,stroke:#006d77,color:#006d77
    classDef config fill:#f6bd60,stroke:#e76f51,color:#e76f51
    classDef asset fill:#98c1d9,stroke:#2e4057,color:#2e4057
```
