Implement Backend Documentation Structure (SOTA 2026)

apps/daemon/backend/pyproject.toml

@@ -30,6 +30,14 @@ dependencies = [
     "aiofiles",
 ]
 
+[project.optional-dependencies]
+docs = [
+    "mkdocs>=1.6.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocs-static-i18n>=1.2.0",
+    "mkdocstrings[python]>=0.24.0",
+]
+
 [tool.ruff]
 # Habilitar reglas modernas de Python
 target-version = "py312"

docs/docs/backend/adr/0001-estructura-diataxis.en.md

@@ -0,0 +1,13 @@
+# 1. Adoption of Diátaxis and Docs-as-Code
+
+* **Status:** Accepted
+* **Date:** 2026-01-20
+
+## Context
+We need scalable documentation that differentiates between learning material and pure technical reference.
+
+## Decision
+Adopt the **Diátaxis** framework and centralize documentation in the monorepo using MkDocs.
+
+## Consequences
+Backend documentation will live alongside the code in `docs/docs/backend`, allowing atomic updates in PRs.

docs/docs/backend/adr/0001-estructura-diataxis.es.md

@@ -0,0 +1,13 @@
+# 1. Adopción de Diátaxis y Docs-as-Code
+
+* **Estado:** Aceptado
+* **Fecha:** 2026-01-20
+
+## Contexto
+Necesitamos una documentación escalable que diferencie entre material de aprendizaje y referencia técnica pura.
+
+## Decisión
+Adoptar el framework **Diátaxis** y centralizar la documentación en el monorepo usando MkDocs.
+
+## Consecuencias
+La documentación del backend vivirá junto al código en `docs/docs/backend`, permitiendo actualizaciones atómicas en los PRs.

docs/docs/backend/adr/index.en.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records (ADRs)
+
+Architecture decision records for the Backend.
+
+* [1. Adoption of Diátaxis and Docs-as-Code](0001-estructura-diataxis.md)

docs/docs/backend/adr/index.es.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records (ADRs)
+
+Registro de decisiones de arquitectura para el Backend.
+
+* [1. Adopción de Diátaxis y Docs-as-Code](0001-estructura-diataxis.md)

docs/docs/backend/explanation/index.en.md

@@ -0,0 +1,5 @@
+# Concept Explanation
+
+Deep dive into architecture and design.
+
+* *Coming soon: Why we use Rust for the audio buffer.*

docs/docs/backend/explanation/index.es.md

@@ -0,0 +1,5 @@
+# Explicación de Conceptos
+
+Profundización en la arquitectura y diseño.
+
+* *Próximamente: Por qué usamos Rust para el buffer de audio.*

docs/docs/backend/how-to/index.en.md

@@ -0,0 +1,5 @@
+# How-To Guides
+
+Quick solutions to common problems.
+
+* *Coming soon: How to configure a new local LLM provider.*

docs/docs/backend/how-to/index.es.md

@@ -0,0 +1,5 @@
+# Guías How-To
+
+Soluciones rápidas a problemas comunes.
+
+* *Próximamente: Cómo configurar un nuevo proveedor de LLM local.*

docs/docs/backend/index.en.md

@@ -0,0 +1,12 @@
+# Backend Daemon (Core)
+
+Welcome to the technical documentation of the Voice2Machine core. This component is responsible for audio orchestration, VAD (Voice Activity Detection), and communication with LLMs.
+
+## 🧭 Diátaxis Navigation
+
+The documentation is organized according to the type of need:
+
+* **[🎓 Tutorials](tutorials/index.md)**: Learn step-by-step how the system works.
+* **[🛠️ How-To Guides](how-to/index.md)**: Recipes for specific tasks (e.g., adding a model).
+* **[📚 Technical Reference](reference/index.md)**: Detailed API generated from the code.
+* **[🧠 Explanation](explanation/index.md)**: Understand hexagonal architecture and design decisions.

docs/docs/backend/index.es.md

@@ -0,0 +1,12 @@
+# Backend Daemon (Core)
+
+Bienvenido a la documentación técnica del núcleo de Voice2Machine. Este componente es responsable de la orquestación de audio, VAD (Voice Activity Detection) y la comunicación con los LLMs.
+
+## 🧭 Navegación Diátaxis
+
+La documentación está organizada según el tipo de necesidad:
+
+* **[🎓 Tutoriales](tutorials/index.md)**: Aprende paso a paso cómo funciona el sistema.
+* **[🛠️ Guías How-To](how-to/index.md)**: Recetas para tareas específicas (ej. añadir un modelo).
+* **[📚 Referencia Técnica](reference/index.md)**: API detallada autogenerada del código.
+* **[🧠 Explicación](explanation/index.md)**: Entiende la arquitectura hexagonal y decisiones de diseño.

docs/docs/backend/reference/index.en.md

@@ -0,0 +1,15 @@
+# API Reference
+
+This section is automatically generated from source code docstrings in `apps/daemon/backend/src`.
+
+## Core Services
+
+::: v2m.services.orchestrator
+    options:
+      heading_level: 3
+
+## Domain and Ports
+
+::: v2m.domain.ports
+    options:
+      heading_level: 3

docs/docs/backend/reference/index.es.md

@@ -0,0 +1,15 @@
+# Referencia de API
+
+Esta sección se genera automáticamente a partir de los docstrings del código fuente en `apps/daemon/backend/src`.
+
+## Servicios Principales
+
+::: v2m.services.orchestrator
+    options:
+      heading_level: 3
+
+## Dominio y Puertos
+
+::: v2m.domain.ports
+    options:
+      heading_level: 3

docs/docs/backend/tutorials/index.en.md

@@ -0,0 +1,5 @@
+# Tutorials
+
+Step-by-step guides for developers new to the project.
+
+* *Coming soon: Lifecycle of a transcription.*

docs/docs/backend/tutorials/index.es.md

@@ -0,0 +1,5 @@
+# Tutoriales
+
+Guías paso a paso para desarrolladores nuevos en el proyecto.
+
+* *Próximamente: Flujo de vida de una transcripción.*

mkdocs.yml

@@ -32,6 +32,25 @@ theme:
   icon:
     repo: fontawesome/brands/github
 
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [apps/daemon/backend/src]
+          import:
+            - https://docs.python.org/3/objects.inv
+  - i18n:
+      docs_structure: suffix
+      languages:
+        - locale: es
+          default: true
+          name: Español
+          build: true
+        - locale: en
+          name: English
+          build: true
+
 markdown_extensions:
   - admonition
   - pymdownx.details
@@ -66,3 +85,10 @@ nav:
       - Changelog: es/changelog.md
   - Gobernanza:
       - Guía de Estilo: es/style_guide.md
+  - Core (Daemon):
+      - Inicio: backend/index.md
+      - 🎓 Tutoriales: backend/tutorials/index.md
+      - 🛠️ How-To: backend/how-to/index.md
+      - 📚 Referencia API: backend/reference/index.md
+      - 🧠 Explicación: backend/explanation/index.md
+      - 🏛️ Arquitectura (ADR): backend/adr/index.md