En esta guía (25 elementos)

LaTeX Architecture Docs

LaTeX for Architecture Commands & Documentation Generation

MANDATORY FOR ALL AI AGENTS: This is the canonical guide when an /arch-* command, the software-architect skill, or /arch-doc is asked to produce a board-grade PDF deliverable instead of (or in addition to) the default HTML+Mermaid output. Use LaTeX only when the user asks for PDF / print / signed deliverable / regulator-grade output. Default remains HTML+Mermaid per arch-doc-spec.md.

Companion documents:

Architecture Document Spec — the 21-section structural contract (format-agnostic).
Diagrams — diagram catalog (Mermaid is default; TikZ is the LaTeX equivalent).
Gradle §4.x — build integration (Structurizr export, PlantUML).

1. When to use LaTeX vs Markdown/HTML

Output need	Format	Why
Living docs, fast iteration, in-repo review	HTML + Mermaid (default)	Browser-native, no toolchain, version-control diff-friendly
Internal team reading, PR comments	Markdown	Diff-friendly, GitHub-rendered
Architecture Review Board (ARB) deliverable, audit evidence, regulator submission, executive sign-off, printed signature copy	LaTeX → PDF	Page numbering, ToC, cross-refs, glossary, biblio, deterministic layout, vector diagrams
Mixed: HTML in repo + PDF for board	Pandoc bridge — author once in Markdown, render both	Single source of truth

Rule: never hand-author LaTeX for content that lives in HTML/Markdown elsewhere. Author once, transform.

2. Toolchain (pick one)

Option	When	Setup
Tectonic (recommended)	Default for AI-driven generation	`brew install tectonic`. Self-contained, auto-fetches packages, reproducible, no system TeX Live needed.
TeX Live + latexmk	Existing TeX Live installs, large org standardization	`brew install --cask mactex-no-gui` or `brew install texlive`; `latexmk -pdf`.
Pandoc (bridge)	Author in Markdown, render LaTeX/PDF	`brew install pandoc`. Use with Tectonic engine: `pandoc -t latex --pdf-engine=tectonic`.

Forbidden: Overleaf-only workflows. Architecture deliverables MUST build locally + in CI from repo sources.

3. Repo layout

1
docs/architecture/
2
├── README.md                       # how to build, where artifacts go
3
├── src/
4
│   ├── architecture-document.tex   # main file — \input{} other sections
5
│   ├── preamble.tex                # packages, macros, colors, geometry
6
│   ├── titlepage.tex
7
│   ├── sections/
8
│   │   ├── 01-purpose.tex
9
│   │   ├── 02-scope.tex
10
│   │   ├── 03-stakeholders.tex
11
│   │   ├── 04-adrs.tex             # \input{../../adr/*.tex} or auto-gen from docs/adr/*.md
12
│   │   ├── 08-context-map.tex
13
│   │   ├── 09-c4-l1.tex             # TikZ C4 model
14
│   │   ├── 10-c4-l2.tex
15
│   │   ├── 11-c4-l3.tex
16
│   │   ├── 12-event-catalog.tex
17
│   │   ├── 14-threat-model.tex      # STRIDE table
18
│   │   ├── 15-nfr.tex
19
│   │   ├── 19-risk-register.tex
20
│   │   └── ...                      # 21 mandatory sections (see arch-doc-spec.md)
21
│   ├── diagrams/
22
│   │   ├── c4-l1.tex                # TikZ source
23
│   │   ├── data-flow.tex
24
│   │   └── *.plantuml               # rendered to PDF via Gradle/plantuml-jar
25
│   ├── tables/
26
│   │   ├── stride-findings.tex
27
│   │   └── nfr-targets.tex
28
│   ├── glossary.tex                 # acronyms (DDD, CQRS, STRIDE, NFR…)
29
│   └── bibliography.bib             # biblatex refs (Evans DDD, Fowler, NIST, OWASP)
30
├── build/                           # gitignored: PDFs, .aux, .log, .toc
31
└── Makefile                         # `make pdf`, `make watch`, `make clean`

Do not check in build/. PDFs go to dist/ or release artifact storage.

4. Preamble (`preamble.tex`)

Locked baseline — extend per project, never delete:

1
\documentclass[11pt,a4paper,twoside,openright]{report}
2

3
% --- Layout
4
\usepackage[a4paper,margin=2.5cm,headheight=14pt]{geometry}
5
\usepackage{fancyhdr}
6
\usepackage{microtype}
7
\usepackage{parskip}
8

9
% --- Fonts
10
\usepackage{fontspec}                  % requires xelatex / lualatex / tectonic
11
\setmainfont{Inter}[Scale=1.0]         % fallback: Latin Modern Roman
12
\setmonofont{JetBrains Mono}[Scale=0.9]
13

14
% --- Colors (corporate palette — override per project)
15
\usepackage{xcolor}
16
\definecolor{archblue}{HTML}{0B5FFF}
17
\definecolor{archteal}{HTML}{009688}
18
\definecolor{archred}{HTML}{D32F2F}
19
\definecolor{archgrey}{HTML}{37474F}
20
\definecolor{codebg}{HTML}{F5F7FA}
21

22
% --- Cross-refs, links, ToC
23
\usepackage[colorlinks=true,linkcolor=archblue,urlcolor=archblue,citecolor=archteal]{hyperref}
24
\usepackage{bookmark}
25
\usepackage{tocbibind}
26

27
% --- Code listings (minted requires --shell-escape + Pygments; listings is pure TeX)
28
\usepackage{listings}
29
\lstdefinestyle{code}{
30
  basicstyle=\ttfamily\small,
31
  backgroundcolor=\color{codebg},
32
  frame=single, rulecolor=\color{archgrey!20},
33
  breaklines=true, captionpos=b, showstringspaces=false,
34
  keywordstyle=\color{archblue}\bfseries,
35
  commentstyle=\color{archgrey!70}\itshape,
36
  stringstyle=\color{archteal}
37
}
38
\lstset{style=code}
39

40
% --- Tables
41
\usepackage{booktabs}
42
\usepackage{longtable}
43
\usepackage{tabularx}
44
\usepackage{array}
45
\usepackage{multirow}
46

47
% --- Diagrams
48
\usepackage{tikz}
49
\usetikzlibrary{positioning,shapes,arrows.meta,fit,calc,backgrounds,decorations.pathreplacing}
50
\usepackage{pgfplots}\pgfplotsset{compat=1.18}
51

52
% --- Glossary / acronyms
53
\usepackage[acronym,toc,nopostdot]{glossaries}
54
\makenoidxglossaries
55

56
% --- Bibliography (biblatex)
57
\usepackage[backend=biber,style=ieee,sorting=none]{biblatex}
58
\addbibresource{bibliography.bib}
59

60
% --- Diagram package: C4 model in TikZ
61
% No canonical CTAN package for C4 — define the styles manually.
62
% Use the TikZ classDef shown in §6.1 of this guide (vendor it under src/sty/c4tikz.sty).
63

64
% --- Page style
65
\pagestyle{fancy}
66
\fancyhf{}
67
\fancyhead[LE,RO]{\thepage}
68
\fancyhead[RE]{\nouppercase{\leftmark}}
69
\fancyhead[LO]{\nouppercase{\rightmark}}
70
\renewcommand{\headrulewidth}{0.4pt}
71

72
% --- Reusable macros
73
\newcommand{\arch}[1]{\textcolor{archblue}{\textbf{#1}}}
74
\newcommand{\adrref}[1]{\hyperref[adr:#1]{ADR-#1}}
75
\newcommand{\stridecell}[1]{\textcolor{archred}{\textbf{#1}}}
76
\newcommand{\nfrcell}[1]{\textcolor{archteal}{\textbf{#1}}}
77
\newcommand{\portname}[1]{\texttt{\textcolor{archblue}{#1}}}

5. Main document skeleton (`architecture-document.tex`)

1
\input{preamble.tex}
2

3
\title{\textbf{\Huge Platform Architecture} \\[0.5em] \Large Platform --- Example}
4
\author{Andres Montoya \\ \small Solutions Architecture}
5
\date{\today \quad | \quad Version 1.0}
6

7
\input{glossary.tex}
8

9
\begin{document}
10
\input{titlepage.tex}
11
\tableofcontents
12
\listoffigures
13
\listoftables
14
\printnoidxglossary[type=acronym,title=Acronyms]
15

16
\input{sections/01-purpose.tex}
17
\input{sections/02-scope.tex}
18
\input{sections/03-stakeholders.tex}
19
\input{sections/04-adrs.tex}
20
\input{sections/05-quality-attributes.tex}
21
\input{sections/06-constraints.tex}
22
\input{sections/07-principles.tex}
23
\input{sections/08-context-map.tex}
24
\input{sections/09-c4-l1.tex}
25
\input{sections/10-c4-l2.tex}
26
\input{sections/11-c4-l3.tex}
27
\input{sections/12-event-catalog.tex}
28
\input{sections/13-data-architecture.tex}
29
\input{sections/14-threat-model.tex}
30
\input{sections/15-nfr.tex}
31
\input{sections/16-deployment.tex}
32
\input{sections/17-observability.tex}
33
\input{sections/18-evolution.tex}
34
\input{sections/19-risk-register.tex}
35
\input{sections/20-glossary.tex}
36
\input{sections/21-references.tex}
37

38
\printbibliography[heading=bibintoc,title=References]
39
\end{document}

A board-grade section layout (adapt to your arch-doc-spec.md section set). Section files are short — each \input{}-able, regenerable per --ddd-only, --events-only, --stride-only, --risks-only flags of /arch-doc.

6. Diagrams in LaTeX

6.1 C4 model (TikZ)

C4 boxes via vendored c4tikz.sty or manual TikZ. Example L1 (System Context):

1
\begin{figure}[ht]
2
\centering
3
\begin{tikzpicture}[
4
  node distance=2.5cm,
5
  person/.style={
6
    rectangle, rounded corners=12pt,
7
    fill=archblue, text=white, minimum width=2.8cm, minimum height=1.4cm, align=center
8
  },
9
  system/.style={
10
    rectangle, fill=archteal, text=white, minimum width=3.2cm, minimum height=1.6cm, align=center
11
  },
12
  external/.style={
13
    rectangle, fill=archgrey!60, text=white, minimum width=3cm, minimum height=1.4cm, align=center
14
  },
15
  rel/.style={-Stealth, thick, archgrey, font=\scriptsize}
16
]
17
  \node[person] (operator) {Raffle\\Operator};
18
  \node[system, right=of operator] (platform) {Platform};
19
  \node[external, right=of platform] (stripe) {Stripe\\API};
20
  \node[external, below=of platform] (sms) {SMS\\Gateway};
21

22
  \draw[rel] (operator) -- node[above]{HTTPS / OIDC} (platform);
23
  \draw[rel] (platform) -- node[above]{Payments REST} (stripe);
24
  \draw[rel] (platform) -- node[right]{Notifications} (sms);
25
\end{tikzpicture}
26
\caption{C4 L1 --- System Context}
27
\label{fig:c4-l1}
28
\end{figure}

6.2 Mermaid → PDF bridge

When existing diagrams are Mermaid (in HTML), render via Mermaid CLI to SVG then include:

mmdc -i diagrams/data-flow.mmd -o diagrams/data-flow.pdf -b transparent

1
\begin{figure}[ht]
2
\centering
3
\includegraphics[width=0.9\textwidth]{diagrams/data-flow.pdf}
4
\caption{Order checkout data flow}
5
\label{fig:data-flow}
6
\end{figure}

6.3 PlantUML → PDF

Use Gradle PlantUML plugin (already documented in gradle.md) producing *.pdf artifacts, then \includegraphics.

6.4 Structurizr → PUML → PDF

Pipeline: Structurizr DSL → structurizrExport (PlantUML) → plantuml -tpdf → \includegraphics. Same as HTML pipeline but with -tpdf instead of -tsvg.

7. Tables — STRIDE, NFR, Risk Register

7.1 STRIDE findings (`tables/stride-findings.tex`)

1
\begin{longtable}{@{}p{2.4cm} p{3.2cm} p{1.6cm} p{4.8cm} p{2.4cm}@{}}
2
\caption{STRIDE Findings --- Order Service}\label{tab:stride-orders}\\
3
\toprule
4
\textbf{Category} & \textbf{Asset} & \textbf{Severity} & \textbf{Mitigation} & \textbf{Owner} \\
5
\midrule
6
\endfirsthead
7
\toprule
8
\textbf{Category} & \textbf{Asset} & \textbf{Severity} & \textbf{Mitigation} & \textbf{Owner} \\
9
\midrule
10
\endhead
11
\stridecell{Spoofing}        & Operator JWT      & High   & OIDC + audience claim verification & Platform \\
12
\stridecell{Tampering}       & Outbox payload    & Medium & HMAC signature on event body       & Backend  \\
13
\stridecell{Repudiation}     & Refund action     & High   & Append-only audit log + traceId    & Backend  \\
14
\stridecell{Info disclosure} & PII in logs       & Critical & Structured log scrubber + DLP rule & Platform \\
15
\stridecell{DoS}             & Public REST       & Medium & Rate limit per tenant + WAF        & Platform \\
16
\stridecell{EoP}             & Tenant boundary   & Critical & ABAC policy + integration test     & Backend  \\
17
\bottomrule
18
\end{longtable}

7.2 NFR target table (`tables/nfr-targets.tex`)

1
\begin{table}[ht]
2
\centering
3
\begin{tabularx}{\textwidth}{@{}lXll@{}}
4
\toprule
5
\textbf{Attribute} & \textbf{Scenario} & \textbf{Target} & \textbf{Measure} \\
6
\midrule
7
\nfrcell{Availability} & Operator REST p95 monthly         & 99.9\%    & Prometheus uptime  \\
8
\nfrcell{Latency}      & Ticket reservation p95            & < 250ms   & RED metric         \\
9
\nfrcell{Throughput}   & Outbox publisher                  & 2k msg/s  & Kafka lag          \\
10
\nfrcell{Recovery}     & Cold start after region failover  & RTO 15min & DR drill quarterly \\
11
\bottomrule
12
\end{tabularx}
13
\caption{Non-Functional Requirements --- v2.4}
14
\end{table}

7.3 Risk register (`sections/19-risk-register.tex`)

8. ADR rendering

Two strategies:

A. Hand-authored LaTeX ADRs under docs/adr/tex/ADR-NNNN-<slug>.tex, \input{} from section 04.

B. Pandoc bridge from Markdown ADRs (docs/adr/*.md via MADR template):

for f in docs/adr/*.md; do
  base=$(basename "$f" .md)
  pandoc "$f" -o "docs/architecture/src/sections/adr/${base}.tex" \
    --top-level-division=section --wrap=preserve --to=latex
done

Then in 04-adrs.tex:

1
\chapter{Architectural Decision Records}
2
\foreach \adr in {0001,0002,0003,...} {
3
  \input{sections/adr/ADR-\adr-slug.tex}
4
}

Recommended: use B. Single source of truth, ADRs live in docs/adr/*.md, board PDF auto-generated.

9. Build commands

9.1 Tectonic (recommended)

cd docs/architecture
tectonic -X compile src/architecture-document.tex --outdir build --keep-logs
mv build/architecture-document.pdf dist/architecture-v$(date +%Y%m%d).pdf

9.2 latexmk (TeX Live)

cd docs/architecture
latexmk -pdf -xelatex -interaction=nonstopmode -outdir=build src/architecture-document.tex

9.3 Pandoc bridge (Markdown → PDF)

pandoc docs/architecture/src/*.md \
  --from markdown+raw_tex \
  --to latex \
  --pdf-engine=tectonic \
  --template templates/arch.tex \
  --toc --toc-depth=2 \
  --bibliography src/bibliography.bib \
  --citeproc \
  -o dist/architecture-$(git describe --tags --always).pdf

9.4 Makefile (canonical)

1
PDF_OUT := dist/architecture-$(shell git describe --tags --always).pdf
2
SRC     := src/architecture-document.tex
3

4
.PHONY: pdf watch clean adr-bridge diagrams
5

6
pdf: adr-bridge diagrams
7
  mkdir -p build dist
8
  tectonic -X compile $(SRC) --outdir build --keep-logs
9
  cp build/architecture-document.pdf $(PDF_OUT)
10
  @echo "→ $(PDF_OUT)"
11

12
watch:
13
  tectonic -X watch --src $(SRC)
14

15
adr-bridge:
16
  @for f in ../adr/*.md; do \
17
    base=$$(basename $$f .md); \
18
    pandoc $$f -o src/sections/adr/$$base.tex --top-level-division=section --to=latex; \
19
  done
20

21
diagrams:
22
  @for f in src/diagrams/*.mmd; do \
23
    mmdc -i $$f -o $${f%.mmd}.pdf -b transparent; \
24
  done
25
  @for f in src/diagrams/*.plantuml; do \
26
    plantuml -tpdf -o ../$(dir $$f) $$f; \
27
  done
28

29
clean:
30
  rm -rf build dist

10. CI integration (GitHub Actions)

1
name: arch-doc-pdf
2
on:
3
  push:
4
    paths: ['docs/architecture/**', 'docs/adr/**']
5
  workflow_dispatch:
6

7
jobs:
8
  build:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v5
12
      - name: Install Tectonic
13
        run: |
14
          curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh
15
          sudo mv tectonic /usr/local/bin/
16
      - name: Install Pandoc + Mermaid CLI + PlantUML
17
        run: |
18
          sudo apt-get update
19
          sudo apt-get install -y pandoc plantuml graphviz
20
          npm install -g @mermaid-js/mermaid-cli
21
      - name: Build PDF
22
        working-directory: docs/architecture
23
        run: make pdf
24
      - name: Upload artifact
25
        uses: actions/upload-artifact@v5
26
        with:
27
          name: architecture-pdf
28
          path: docs/architecture/dist/*.pdf
29
          retention-days: 90

Gate ARB approval on this artifact (require successful build before merging architecture-document changes).

11. Integration with `/arch-*` commands

Command	LaTeX touchpoint
`/arch-doc`	Add `--format=latex` flag → scaffolds `docs/architecture/src/` skeleton from this guide instead of single HTML. `--format=both` generates HTML+LaTeX from same Markdown source via Pandoc.
`/arch-adr`	When ADR is accepted, run Pandoc Markdown→LaTeX into `docs/architecture/src/sections/adr/`.
`/arch-threat`	STRIDE table output → emit both Markdown (HTML rendering) and `tables/stride-findings.tex` (LaTeX).
`/arch-deps`	CVE / version drift table → `tables/cve-findings.tex` for board PDF.
`/arch-perf`	PERF-AUDIT.md → optional Pandoc-render into appendix `sections/22-performance-audit.tex`.
`/arch-review`	REVIEW.md → optional appendix.

The HTML output remains the default and primary. LaTeX is an opt-in escalation for board-grade artifacts.

Required updates when wiring `--format=latex` into `/arch-doc`

Add flag handling to ~/.claude/commands/arch-doc.md.
Add scaffolding step: create docs/architecture/src/{preamble.tex,architecture-document.tex,sections/,diagrams/,tables/} skeleton.
Add Makefile from §9.4.
Add CI workflow stub from §10.
Verify Tectonic available locally: command -v tectonic || echo "Install: brew install tectonic".

12. Anti-patterns (do NOT do)

❌ Hand-author duplicate content in LaTeX when it lives in HTML/Markdown. Single source of truth via Pandoc.
❌ Embed binary PDFs of diagrams in the repo. Generate from source (*.mmd, *.plantuml, *.tex TikZ) at build time.
❌ Use \usepackage{minted} without committing to --shell-escape + Pygments availability in CI. Default to listings.
❌ Inline \textcolor{red}{...} arbitrarily. Use semantic macros (\stridecell, \nfrcell, \portname).
❌ Skip \label{} + \ref{} for figures and tables. Cross-refs are mandatory for board readability.
❌ Commit build/ artifacts to git. Gitignore everything under docs/architecture/build/.
❌ Use pdflatex when the preamble loads fontspec. Always Tectonic / XeLaTeX / LuaLaTeX.
❌ Pin texlive-full Docker image (~5GB) in CI. Use Tectonic (~50MB).

13. Quick decision matrix

Question	Answer
Need a PDF for ARB next week?	LaTeX via Tectonic + Pandoc bridge (§9.3).
Adding a new ADR to the deliverable?	Author in Markdown under `docs/adr/`, regenerate PDF via `make pdf`.
Need to update only the threat model section?	Run `/arch-threat`, copy table output to `tables/stride-findings.tex`, rebuild.
First-time setup in a repo?	Run `/arch-doc --format=latex <slug>` → scaffolds `docs/architecture/` from this guide.
CI broke on missing font?	Install Inter + JetBrains Mono in the runner, or fall back to `\setmainfont{Latin Modern Roman}` (always present).
Diagram is a Mermaid block in HTML doc?	Bridge via `mmdc -o foo.pdf`, `\includegraphics{foo.pdf}`.