docs: publish architecture documentation via mdBook and GitHub Pages (closes #28)

.github/workflows/pages.yml

@@ -0,0 +1,56 @@
+name: Deploy architecture docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - apotheosis2
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+env:
+  MDBOOK_VERSION: "0.5.4"
+  MDBOOK_MERMAID_VERSION: "0.17.0"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install mdBook and mdbook-mermaid
+        run: |
+          mkdir -p "$HOME/.local/bin"
+          curl -sSL "https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz" | tar -xz -C "$HOME/.local/bin"
+          curl -sSL "https://github.com/badboy/mdbook-mermaid/releases/download/v${MDBOOK_MERMAID_VERSION}/mdbook-mermaid-v${MDBOOK_MERMAID_VERSION}-x86_64-unknown-linux-gnu.tar.gz" | tar -xz -C "$HOME/.local/bin"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/book
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -72,6 +72,9 @@ instance/
 # Sphinx documentation
 docs/_build/
 
+# mdBook build output
+docs/book/
+
 # PyBuilder
 .pybuilder/
 target/

_typos.toml

@@ -3,3 +3,11 @@
 # typos uses an English dictionary and would flag these as misspellings.
 "Estratégicos" = "Estratégicos"
 Ciberseguridad = "Ciberseguridad"
+# Spanish filename convention used across the three architecture views
+# (vista-modulos.md, vista-cc.md, vista-distribucion.md).
+distribucion = "distribucion"
+
+[files]
+# Vendored, minified third-party JS. Its internal identifiers are not
+# meant to be readable text and trigger constant false positives.
+extend-exclude = ["docs/mermaid.min.js"]

docs/architecture/README.md

@@ -0,0 +1,39 @@
+# Architectural Documentation: APOTHEOSIS2
+
+Framework: **Views & Beyond** (Clements et al.)
+
+**Start here:** read [roadmap.md](roadmap.md) first. It describes what each document covers, which document to read depending on your role, and how the views relate to each other.
+
+## Views
+
+| View | File | Status |
+|-------|---------|--------|
+| Module | [views/module/vista-modulos.md](views/module/vista-modulos.md) | Complete |
+| Component and Connector (C&C) | [views/cc/vista-cc.md](views/cc/vista-cc.md) | Complete |
+| Deployment | [views/deployment/vista-distribucion.md](views/deployment/vista-distribucion.md) | Complete |
+
+## Cross-cutting Documents
+
+- [Roadmap](roadmap.md)
+- [Quality Attributes](quality-attributes.md): design drivers, out-of-scope attributes, and mapping to the three views
+- [Directory and Data Dictionary](directory.md): glossary, acronyms, central type catalog, and bibliographic references
+
+## Folder Structure
+
+```
+docs/architecture/
+├── README.md                        ← this file
+├── roadmap.md
+├── quality-attributes.md             ← quality attributes: drivers, trade-offs, and cross-view mapping
+├── directory.md                     ← glossary, acronyms, data dictionary, and references
+└── views/
+    ├── module/
+    │   ├── vista-modulos.md
+    │   └── assets/                  ← PNGs/SVGs of the module diagram
+    ├── cc/
+    │   ├── vista-cc.md
+    │   └── assets/
+    └── deployment/
+        ├── vista-distribucion.md
+        └── assets/
+```

docs/architecture/SUMMARY.md

@@ -0,0 +1,15 @@
+# Summary
+
+[Architectural Documentation](README.md)
+
+# Cross-cutting
+
+- [Roadmap](roadmap.md)
+- [Quality Attributes](quality-attributes.md)
+- [Directory and Data Dictionary](directory.md)
+
+# Views
+
+- [Module View](views/module/vista-modulos.md)
+- [Component and Connector View](views/cc/vista-cc.md)
+- [Deployment View](views/deployment/vista-distribucion.md)