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/

README.md

@@ -52,7 +52,7 @@ fn main() {
 
     let query = TlshDefault::from_str("<tlsh_hash_a>").expect("invalid TLSH hash");
 
-    // Pass None for ef_search; the effective value is 24.
+    // Passing None for ef_search applies the library default.
     let results: Vec<(u32, &SimpleTlshRecord)> = index.search(&query, 5, None);
 
     for (distance, record) in &results {
@@ -63,7 +63,7 @@ fn main() {
 
 ### Persistence and export
 
-A built model can be saved to disk and loaded back. `load()` validates the M, M0 and EF parameters in the file header against the loading type. The HNSW graph can also be exported to GEXF files (one per layer).
+A built model can be saved to disk and loaded back. `load()` validates the M, M0, EF and HEURISTIC parameters and the distance type recorded in the file header against the loading type, and refuses to load on any mismatch. The HNSW graph can also be exported to GEXF files (one per layer).
 
 ```rust
 // dump() and load() return Result.

_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,42 @@
+# 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)
+- [Interface Documentation](interfaz-apotheosis.md): the public API boundary of the crate, its provided resources, error handling, variability, and usage examples
+- [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
+├── SUMMARY.md                       ← table of contents used to build the site
+├── roadmap.md
+├── interfaz-apotheosis.md           ← public API boundary: resources, errors, variability, examples
+├── 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,16 @@
+# Summary
+
+[Architectural Documentation](README.md)
+
+# Cross-cutting
+
+- [Roadmap](roadmap.md)
+- [Interface Documentation](interfaz-apotheosis.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)