# balajicm24/texmantra architecture

> Architecture diagram of the GitHub repository balajicm24/texmantra, 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/balajicm24/texmantra
- Repository: https://github.com/balajicm24/texmantra

## Overview

#### Purpose and Scope
TeXMantra is a Django-based journal-production workflow system covering article typesetting, LaTeX compilation, JATS XML creation/validation, and role-based handoff from typesetting to XML production. The only supplied repository artifact is [`README.md`](README.md); implementation layout and executable files are not available for verification.

#### Application Entry and Runtime Topology
The documented application runtime is Django 4.2, served with Daphne for ASGI/WebSocket traffic. Celery workers execute long-running processing, while Redis serves as both message broker and cache. Development uses SQLite; production targets PostgreSQL. Document tooling is installed as external system dependencies. Source entry-point paths cannot be identified beyond [`README.md`](README.md).

#### LaTeX Editing and Compilation Stage
The LaTeX editor is the first principal production stage: a browser IDE based on Monaco edits article source, supports version-oriented editing, and exposes compile output and PDF preview. Compilation invokes external TeX Live tools—`pdflatex`, `xelatex`, `lualatex`, `bibtex`, and `biber`—and supports SyncTeX source/PDF navigation. Long-running compile jobs cross from Django requests into Celery rather than blocking the UI. Documented in [`README.md`](README.md).

#### Conversion and Artifact Boundary
Compiled/source documents can be exported to HTML, DOCX, and JATS XML through Pandoc. This is a material boundary between LaTeX-oriented typesetting artifacts and structured publishing XML. Generated files and workflow-managed copies are expected to be path-controlled; the README identifies directory-traversal prevention and dangerous-LaTeX-command validation as security controls. Documented in [`README.md`](README.md).

#### XML Editing, Validation, and Preview Stage
The XML module is specialized for JATS finalization. It combines a file explorer, XML editor, and transformed preview, with JATS-aware completion/validation and source-to-preview synchronization. XSLT transformation is performed server-side with Saxon-HE (XSLT 2.0/3.0) or client-side with lxml, creating a clear boundary between XML authoring and rendered preview. Documented in [`README.md`](README.md).

#### Workflow, Access, and Collaboration
A guided “TS → XML” workflow coordinates task status, file movement, and assignment between Typeset and XML users. Authorization distinguishes SuperAdmin, Admin, TypesetUser, and XMLUser roles. Real-time collaboration, presence, and compilation logs use Django Channels/WebSockets; dashboard analytics use Chart.js. Redis is therefore operationally required for both collaboration and asynchronous work. Documented in [`README.md`](README.md).

#### Key External Dependencies
Core infrastructure/services are Redis, PostgreSQL in production, Celery workers, and Daphne. Core document-processing dependencies are TeX Live, Pandoc, Saxon-HE, and libmagic. Frontend architecture is server-rendered Django augmented with Bootstrap, jQuery, Monaco, PDF.js, Split.js, and jsTree rather than a separately evidenced SPA. See [`README.md`](README.md).

Main entry points: [`README.md`](https://github.com/balajicm24/texmantra/blob/main/README.md) (Document safety controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Django application"]
  node_browser["Production UI<br/>server-rendered frontend"]
  node_django["Django application<br/>workflow application"]
  node_channels["Django Channels<br/>realtime layer"]
  node_access["Roles and access<br/>authorization"]
  node_security["Document safety controls<br/>file security<br/>[README.md]"]
end

subgraph group_production["Production workflow"]
  node_latex_editor["LaTeX editor<br/>typesetting stage"]
  node_compile_jobs["Compile jobs<br/>async processing"]
  node_typeset_artifacts["Typeset artifacts<br/>source and PDF files"]
  node_jats_xml["JATS XML<br/>publishing artifact"]
  node_xml_module["XML finalization<br/>XML editing stage"]
  node_xml_preview["Rendered XML preview<br/>transformed preview"]
  node_ts_xml_workflow["TS → XML workflow<br/>handoff coordinator"]
end

subgraph group_infrastructure["Runtime services"]
  node_daphne{{"Daphne ASGI<br/>ASGI server"}}
  node_celery{{"Celery workers<br/>worker runtime"}}
  node_redis[("Redis<br/>broker and cache")]
  node_database[("PostgreSQL / SQLite<br/>application database")]
end

subgraph group_tools["Document tooling"]
  node_texlive["TeX Live<br/>compiler toolchain"]
  node_pandoc["Pandoc<br/>format converter"]
  node_xslt["Saxon-HE / lxml<br/>XSLT transformer"]
end

node_browser -->|"HTTP and WebSocket"| node_daphne
node_daphne -->|"routes requests"| node_django
node_django -->|"enforces"| node_access
node_django -->|"persists state"| node_database
node_django -->|"realtime features"| node_channels
node_channels -->|"realtime backing"| node_redis
node_browser -->|"edits"| node_latex_editor
node_latex_editor -->|"requests compile"| node_compile_jobs
node_django -->|"dispatches"| node_compile_jobs
node_compile_jobs -->|"executes"| node_celery
node_celery -->|"broker"| node_redis
node_celery -->|"invokes"| node_texlive
node_texlive -->|"produces"| node_typeset_artifacts
node_typeset_artifacts -->|"exports from"| node_pandoc
node_pandoc -->|"generates"| node_jats_xml
node_jats_xml -->|"finalized in"| node_xml_module
node_xml_module -->|"transforms via"| node_xslt
node_xslt -->|"renders"| node_xml_preview
node_ts_xml_workflow -->|"moves managed files"| node_typeset_artifacts
node_ts_xml_workflow -->|"hands off to XML users"| node_xml_module
node_django -->|"coordinates"| node_ts_xml_workflow
node_django -->|"applies"| node_security

click node_security "https://github.com/balajicm24/texmantra/blob/main/README.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_browser,node_django,node_channels,node_access,node_security toneBlue
class node_latex_editor,node_compile_jobs,node_typeset_artifacts,node_jats_xml,node_xml_module,node_xml_preview,node_ts_xml_workflow toneAmber
class node_daphne,node_celery,node_redis,node_database toneMint
class node_texlive,node_pandoc,node_xslt toneRose
```

## Components

### Django application

- **Production UI**: server-rendered frontend · Bootstrap/jQuery UI with Monaco, PDF.js, jsTree, and Chart.js.
- **Django application**: workflow application · Owns roles, workflow state, files, and document-processing requests.
- **Django Channels**: realtime layer · Provides collaboration, presence, and compile logs.
- **Roles and access**: authorization · SuperAdmin, Admin, TypesetUser, and XMLUser permissions.
- [Document safety controls](https://github.com/balajicm24/texmantra/blob/main/README.md): file security · Path control, traversal prevention, and dangerous-LaTeX validation. · `README.md`

### Production workflow

- **LaTeX editor**: typesetting stage · Version-oriented source editing, compile output, and PDF preview.
- **Compile jobs**: async processing · Long-running compilation is dispatched from requests.
- **Typeset artifacts**: source and PDF files · LaTeX source, compiled PDF, SyncTeX, and managed copies.
- **JATS XML**: publishing artifact
- **XML finalization**: XML editing stage · File explorer, XML editor, JATS-aware completion, and validation.
- **Rendered XML preview**: transformed preview · Supports source-to-preview synchronization.
- **TS → XML workflow**: handoff coordinator · Coordinates status, assignment, and file movement between roles.

### Runtime services

- **Daphne ASGI**: ASGI server · Serves Django HTTP and WebSocket traffic.
- **Celery workers**: worker runtime
- **Redis**: broker and cache · Supports Celery and realtime collaboration.
- **PostgreSQL / SQLite**: application database · SQLite in development and PostgreSQL in production.

### Document tooling

- **TeX Live**: compiler toolchain · Runs pdflatex, xelatex, lualatex, BibTeX, and Biber.
- **Pandoc**: format converter · Exports HTML, DOCX, and JATS XML.
- **Saxon-HE / lxml**: XSLT transformer · Server-side Saxon-HE or client-side lxml transformation.

## Connections

- Production UI → Daphne ASGI: HTTP and WebSocket
- Daphne ASGI → Django application: routes requests
- Django application → Roles and access: enforces
- Django application → PostgreSQL / SQLite: persists state
- Django application → Django Channels: realtime features
- Django Channels → Redis: realtime backing
- Production UI → LaTeX editor: edits
- LaTeX editor → Compile jobs: requests compile
- Django application → Compile jobs: dispatches
- Compile jobs → Celery workers: executes
- Celery workers → Redis: broker
- Celery workers → TeX Live: invokes
- TeX Live → Typeset artifacts: produces
- Typeset artifacts → Pandoc: exports from
- Pandoc → JATS XML: generates
- JATS XML → XML finalization: finalized in
- XML finalization → Saxon-HE / lxml: transforms via
- Saxon-HE / lxml → Rendered XML preview: renders
- TS → XML workflow → Typeset artifacts: moves managed files
- TS → XML workflow → XML finalization: hands off to XML users
- Django application → TS → XML workflow: coordinates
- Django application → Document safety controls: applies