Diagramas de Arquitectura¶
Índice de todos los diagramas arquitectónicos de 
SmallCountry. Cada diagrama documenta una dimensión distinta del sistema: desde la vista global hasta los flujos más específicos.
Diagramas obligatorios¶
Estos nueve diagramas constituyen la documentación arquitectónica canónica de SmallCountry. Cada uno responde a una pregunta concreta sobre cómo funciona el sistema.
1. Arquitectura global¶
El mapa completo de las cuatro capas: Hardware → Infraestructura → Servicios → Personas.
Ubicación: Arquitectura resumida
Responde a: ¿Cómo se organiza SmallCountry de arriba a abajo?
2. Topología VPN¶
Conexiones WireGuard y NetBird entre los cuatro nodos. Enlaces primarios, secundarios y redundancia.
Ubicación: Sistema de Comunicaciones y Topologías de red
Responde a: ¿Cómo se conectan Ra, Horus, Geb y Thoth entre sí? ¿Qué pasa si un túnel se cae?
3. Flujo MQTT¶
El recorrido de un dato de sensor desde el ESP32 en el campo hasta el dashboard en Grafana.
Ubicación: Flujos de datos
Responde a: ¿Cómo viaja la información desde una colmena hasta la pantalla de Melissa?
4. Pipeline de Observabilidad¶
El camino de métricas, logs y trazas: emisores → recolección → almacenamiento → visualización → alertas.
Ubicación: Sistema de Observabilidad
Responde a: ¿Cómo sabe SmallCountry que algo va mal antes de que sea tarde?
5. Modo Isla¶
Qué servicios sobreviven sin internet y cómo se reorganiza el sistema en modo autónomo.
Ubicación: Estado Global — Compatibilidad Modo Isla y ADR-022
Responde a: ¿Sigue funcionando SmallCountry si la fibra se corta durante dos semanas?
6. Dependencias IA¶
El pipeline completo de inteligencia artificial local: voz → Whisper → Ollama → Hermes → respuesta.
Ubicación: Sistema de IA Local
Responde a: ¿Qué piezas intervienen cuando alguien le habla al asistente?
7. Flujo energético¶
Generación solar, almacenamiento, distribución y consumo. Perfiles de energía y automatismos de emergencia.
Ubicación: Sistema de Energía
Responde a: ¿Cuánto tiempo puede funcionar SmallCountry sin red eléctrica?
8. Infraestructura física¶
Los cuatro nodos con sus especificaciones, el rack, el cableado, las VLANs y los bridges de Proxmox.
Ubicación: Sistema de Infraestructura y Topologías de red
Responde a: ¿Dónde está cada cosa físicamente y cómo se conecta?
9. Redes entre casas¶
La comunicación entre la finca (Garganta la Olla), la vivienda principal (Chapinería) y el backup offsite (Thoth).
Ubicación: Topologías de red
Responde a: ¿Cómo se conectan dos ubicaciones geográficas separadas 150 km?
Diagramas complementarios¶
Estos diagramas aparecen en páginas específicas del sistema y complementan a los nueve obligatorios:
| Diagrama | Ubicación | Descripción |
|---|---|---|
| Flujo de autenticación | Sistema de Identidad | Secuencia OAuth2/OIDC entre usuario, Caddy, Authentik y servicio |
| Flujo de backup | Flujos de datos | PBS, Restic, rsync y verificación de integridad |
| Flujo de despliegue | Flujos de datos | Forgejo Actions → Ansible → LXC. CI/CD completo |
| Dependencias entre servicios | Dependencias | Grafo de quién necesita a quién para funcionar |
| Topología de red física | Topologías de red | Cableado, switches, VLANs, bridges |
| Topología de red lógica | Topologías de red | Direccionamiento IP, subredes, dominio .sc |
| Mapa de calor de SPOFs | Dependencias | Puntos únicos de fallo y su impacto |
| Ecosistema general | Qué es SmallCountry | Campo + Infraestructura + IA + Personas |
| Principios y su interrelación | Principios Inmutables | Los 12 principios y cómo se refuerzan mutuamente |
Convenciones de diagramas¶
Todos los diagramas de SmallCountry siguen estas convenciones:
| Elemento | Color | Significado |
|---|---|---|
Rosa (#f9a8d4) |
Control y verdad | Fuente única, gobernanza, identidad |
Azul (#90caf9) |
Seguridad y red | VPN, firewall, segmentación, cifrado |
Verde (#a5d6a7) |
Operaciones | Infraestructura, servicios, hardware |
Amarillo (#ffe082) |
Interacción humana | Personas, roles, notificaciones |
Rojo (#ef9a9a) |
Emergencia | Fallos, degradación, puntos únicos de fallo |
Violeta (#ce93d8) |
IA y automatización | Modelos, agentes, flujos automáticos |
Sintaxis: Todos los diagramas usan flowchart LR (horizontal) o flowchart TD (vertical). No se usa graph (sintaxis antigua de Mermaid).
Cómo leer un diagrama¶
- Dirección: Las flechas indican dependencia o flujo de datos.
A --> Bsignifica "A depende de B" o "los datos fluyen de A a B". - Colores: Identifican la categoría del componente, no su estado.
- Subgrafos (
subgraph): Agrupan componentes relacionados. El nombre del subgrafo indica el dominio. - Líneas continuas (
-->): Dependencia fuerte. Si el origen falla, el destino se ve afectado. - Líneas punteadas (
-.->): Dependencia débil o asíncrona. El destino se degrada pero no se cae.