# davidcarlisle/latexcgi architecture

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

- Interactive diagram: https://gitdiagram.com/davidcarlisle/latexcgi
- Repository: https://github.com/davidcarlisle/latexcgi

## Overview

##### Project type and purpose
- This is a full-stack web tool (“latexcgi”) that provides an in-browser LaTeX environment.
- Purpose: serve as a LaTeX server via Perl CGI scripts for learnlatex.org, compiling user-supplied TeX into PDF or HTML (via Make4ht, LaTeXML, Lwarp, etc.) and returning the result through a web interface.

##### File structure
Top-level directories:
- codemirror6 – front-end source for the in-browser editor (based on CodeMirror 6, Rollup build).
- curl – sample client requests or test harness (e.g., tldnet).
- docs – documentation and example HTML pages showing how to embed/run the editor and renderer.
- latexcgilwarp, latexml, lwarp, make4ht, ngpdf – different back-end modules or engines wrapping various TeX→output toolchains.
- perl – the core CGI scripts (e.g., latexcgi, run1, showtags).
Configuration and support files:
- .gitignore, LICENSE, SECURITY.md
- codemirror6/package.json, rollup config
- make4ht/*.4ht, config and sample .tex tests
- docs/*.js HTML wrappers and test pages

##### README for additional context
- Confirms “LaTeX server via perl cgi script”
- Hosted at latexcgi.xyz and tied to learnlatex.org

##### Detailed capture of essential elements
- Fallback or selection logic in the CGI dispatcher
- Rollup build step in codemirror6 before deployment
- Sample data flow: user writes code → editor sends POST → CGI spawns “make4ht” → returns HTML chunk

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser" 
        direction TB
        EditorJS["Editor Core"]:::frontend
        PackageJSON["Package JSON"]:::frontend
        RollupDir["Rollup Build Config"]:::frontend
    end

    %% Static Asset Server
    subgraph "Static Asset Server"
        direction TB
        DocsIndex["docs/index.md"]:::frontend
        RunHTML["docs/run.html"]:::frontend
        RunLatexJS["docs/runlatex.js"]:::frontend
        CM6HTML["docs/cm6/*.html"]:::frontend
        CM6RunJS["docs/cm6/runlatex-cm6.js"]:::frontend
        CM6Tests["docs/cm6/test-*.html"]:::frontend
        Includes["docs/_includes"]:::frontend
        Layouts["docs/_layouts"]:::frontend
    end

    %% Sample Client Harness
    TestHarness["curl/tldnet"]:::frontend

    %% CGI Layer
    subgraph "HTTP/CGI Layer"
        direction TB
        LatexCGI["perl/latexcgi"]:::server
        Run1["perl/run1"]:::server
        ShowTags["perl/showtags"]:::server
    end

    %% Engine Pool
    subgraph "Engine Pool"
        direction TB
        Make4ht["make4ht"]:::engine
        LaTeXML["latexml/latexcgiml"]:::engine
        Lwarp["lwarp/latexcgilwarp"]:::engine
        NGPDF["ngpdf"]:::engine
    end

    %% Storage
    Storage[(Temp Storage)]:::storage

    %% Engine sub-components
    Make4htREADME["make4ht/README.md"]:::engine
    Make4htFilters["make4ht/*.4ht"]:::engine
    Make4htCFG["make4ht/learnlatex4ht.cfg"]:::engine
    Make4htTests["make4ht/test-*.tex"]:::engine

    NGPDFEntry["ngpdf/latexcgi2"]:::engine
    NGPDFHTML["ngpdf/ngpdf.html"]:::engine
    NGPDFCM6HTML["ngpdf/ngpdf-cm6.html"]:::engine
    NGPDFRunJS["ngpdf/runlatex2.js"]:::engine
    NGPDFRunCM6["ngpdf/runlatex2-cm6.js"]:::engine
    NGPDFShow["ngpdf/showtags.html"]:::engine

    %% Layout nodes vertically
    Browser -->|"GET assets"| StaticAssetServer
    subgraph StaticAssetServer[Static Asset Server]
    end

    Browser --> TestHarness

    StaticAssetServer --> DocsIndex
    StaticAssetServer --> RunHTML
    StaticAssetServer --> RunLatexJS
    StaticAssetServer --> CM6HTML
    StaticAssetServer --> CM6RunJS
    StaticAssetServer --> CM6Tests
    StaticAssetServer --> Includes
    StaticAssetServer --> Layouts

    DocsIndex --> EditorJS
    DocsIndex --> RunLatexJS

    EditorJS -->|"POST TeX"| LatexCGI
    TestHarness -->|"POST TeX"| LatexCGI

    LatexCGI -->|"writes .tex"| Storage
    Run1 --> Storage
    ShowTags --> Storage

    LatexCGI --> Make4ht
    LatexCGI --> LaTeXML
    LatexCGI --> Lwarp
    LatexCGI --> NGPDF

    Make4ht --> Make4htREADME
    Make4ht --> Make4htFilters
    Make4ht --> Make4htCFG
    Make4ht --> Make4htTests

    NGPDF --> NGPDFEntry
    NGPDF --> NGPDFHTML
    NGPDF --> NGPDFCM6HTML
    NGPDF --> NGPDFRunJS
    NGPDF --> NGPDFRunCM6
    NGPDF --> NGPDFShow

    Make4ht -->|"PDF/HTML output"| Storage
    LaTeXML -->|"XML/HTML output"| Storage
    Lwarp -->|"PDF→HTML output"| Storage
    NGPDF -->|"PDF output"| Storage

    Storage -->|"read output"| LatexCGI
    LatexCGI -->|"stream response"| EditorJS

    %% Click Events
    click EditorJS "https://github.com/davidcarlisle/latexcgi/blob/main/codemirror6/src/editor.js"
    click PackageJSON "https://github.com/davidcarlisle/latexcgi/blob/main/codemirror6/package.json"
    click RollupDir "https://github.com/davidcarlisle/latexcgi/tree/main/codemirror6/rollup-cm6"

    click DocsIndex "https://github.com/davidcarlisle/latexcgi/blob/main/docs/index.md"
    click RunHTML "https://github.com/davidcarlisle/latexcgi/blob/main/docs/run.html"
    click RunLatexJS "https://github.com/davidcarlisle/latexcgi/blob/main/docs/runlatex.js"
    click CM6HTML "https://github.com/davidcarlisle/latexcgi/tree/main/docs/cm6"
    click CM6RunJS "https://github.com/davidcarlisle/latexcgi/blob/main/docs/cm6/runlatex-cm6.js"
    click CM6Tests "https://github.com/davidcarlisle/latexcgi/tree/main/docs/cm6"
    click Includes "https://github.com/davidcarlisle/latexcgi/tree/main/docs/_includes"
    click Layouts "https://github.com/davidcarlisle/latexcgi/tree/main/docs/_layouts"

    click TestHarness "https://github.com/davidcarlisle/latexcgi/tree/main/curl/tldnet"

    click LatexCGI "https://github.com/davidcarlisle/latexcgi/tree/main/perl/latexcgi"
    click Run1 "https://github.com/davidcarlisle/latexcgi/tree/main/perl/run1"
    click ShowTags "https://github.com/davidcarlisle/latexcgi/tree/main/perl/showtags"

    click Make4htREADME "https://github.com/davidcarlisle/latexcgi/blob/main/make4ht/README.md"
    click Make4htFilters "https://github.com/davidcarlisle/latexcgi/tree/main/make4ht"
    click Make4htCFG "https://github.com/davidcarlisle/latexcgi/blob/main/make4ht/learnlatex4ht.cfg"
    click Make4htTests "https://github.com/davidcarlisle/latexcgi/tree/main/make4ht"

    click LaTeXML "https://github.com/davidcarlisle/latexcgi/tree/main/latexml/latexcgiml"
    click Lwarp "https://github.com/davidcarlisle/latexcgi/tree/main/lwarp/latexcgilwarp"
    click NGPDFEntry "https://github.com/davidcarlisle/latexcgi/tree/main/ngpdf/latexcgi2"
    click NGPDFHTML "https://github.com/davidcarlisle/latexcgi/blob/main/ngpdf/ngpdf.html"
    click NGPDFCM6HTML "https://github.com/davidcarlisle/latexcgi/blob/main/ngpdf/ngpdf-cm6.html"
    click NGPDFRunJS "https://github.com/davidcarlisle/latexcgi/blob/main/ngpdf/runlatex2.js"
    click NGPDFRunCM6 "https://github.com/davidcarlisle/latexcgi/blob/main/ngpdf/runlatex2-cm6.js"
    click NGPDFShow "https://github.com/davidcarlisle/latexcgi/blob/main/ngpdf/showtags.html"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef server fill:#d4edda,stroke:#155724,color:#155724
    classDef engine fill:#fff3cd,stroke:#856404,color:#856404
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757dExplanation
```
