# Descripción del Diseño de Software (SDD)
## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`)
**Estándar:** IEEE Std 1016-2009 / ISO/IEC/IEEE 42010:2011
**Proyecto:** a2host — Lightweight Subdomain Orchestrator
**Versión:** 1.0.0
**Fecha de Emisión:** 19 de Noviembre de 2026
**Clasificación:** Documento de Diseño Técnico
**Autor:** Arquitectura y Redacción Técnica (@docs)
---
### Registro de Revisiones
| Versión | Fecha | Autor | Justificación y Cambios |
| :---: | :---: | :---: | :--- |
| `1.0.0` | 2026-11-19 | Arquitecto de Documentación (@docs) | Versión inicial del diseño de software bajo norma IEEE Std 1016-2009. Especificación de patrones Strategy, Máquina de Estados del Rollback Atómico, Modelo de Datos y Diseño Zero-Build. |
---
## 1. Introducción y Contexto Arquitectónico
### 1.1 Propósito del Documento
El presente documento describe la arquitectura interna, descomposición modular, patrones de diseño, flujos de datos y estructuras de persistencia del sistema **`a2host`**, conforme al estándar internacional **IEEE Std 1016-2009** (*Information Technology — Systems and software engineering — Software Design Descriptions*).
### 1.2 Objetivos Arquitectónicos Primordiales
1. **Ultra-Baja Huella de Recursos (1 GB RAM Target):** Diseñar un sistema con cero sobrecarga en tiempo de ejecución que conviva sin contención con servicios como Gitea (puerto 3000), bases de datos y Apache2 nativo en un VPS con 1 GB de memoria física.
2. **Resiliencia Operativa y Aislamiento de Fallos:** Garantizar que ninguna mala configuración provocada por un usuario o falla de sintaxis pueda desestabilizar el servidor web Apache central mediante el desacoplamiento y un protocolo de *Rollback Atómico*.
3. **Inmunidad a Vulnerabilidades de Inyección:** Eliminar vectores de ataque de inyección de comandos en shell mediante la erradicación del shell subyacente en la ejecución de binarios y validación estricta de cadenas en el perímetro.
4. **Portabilidad y Desacoplamiento de Entorno:** Facilitar el desarrollo, testing automatizado y depuración en estaciones de trabajo locales (macOS, Linux sin Apache) mediante una abstracción por controladores (*Strategy Pattern*).
---
## 2. Vista Lógica y Arquitectura por Capas
El sistema se estructura siguiendo una arquitectura en capas limpias (*Clean Architecture / Hexagonal Ports & Adapters*) adaptada a un runtime ligero en Node.js 22 LTS.
```mermaid
flowchart TD
subgraph PresentationLayer["Capa de Presentación (Zero-Build Frontend)"]
SPA["index.html + app.js (Vanilla ES6+)"]
Tailwind["Tailwind CSS (CDN / Native Utility Tokens)"]
Components["Componentes UI: Modal, Tables, Toast, SystemStatus"]
end
subgraph TransportLayer["Capa de Transporte & Perímetro HTTP"]
Router["Express App Router (/api/*)"]
AuthGuard["AuthMiddleware (HMAC Cookie Guard)"]
RateLimiter["IP Rate Limiter"]
Validator["Input Sanitizer & Schema Validator (Regex Guards)"]
end
subgraph DomainServiceLayer["Capa de Dominio y Servicios de Negocio"]
SubdomainService["SubdomainService (Lifecycle Management)"]
AuthService["AuthService (scrypt & Credential Security)"]
UserService["UserService (Operator Management)"]
TelemetryService["TelemetryService (Memory, Process & Apache Health)"]
TxCoordinator["ApacheTransactionCoordinator (Rollback Engine)"]
end
subgraph InfrastructureLayer["Capa de Infraestructura y Drivers (Strategy Pattern)"]
DriverInterface["«interface»
IApacheDriver"]
RealDriver["RealApacheDriver
(Linux execFile + sudo)"]
MockDriver["MockApacheDriver
(Local Filesystem + Virtual Symlinks)"]
UserRepo["UserRepository
(Atomic JSON / SQLite)"]
end
SPA -->|"JSON via Fetch"| Router
Router --> AuthGuard
AuthGuard --> RateLimiter
RateLimiter --> Validator
Validator --> SubdomainService
Validator --> AuthService
Validator --> UserService
Validator --> TelemetryService
SubdomainService --> TxCoordinator
TxCoordinator --> DriverInterface
AuthService --> UserRepo
UserService --> UserRepo
DriverInterface -.->|VPS Production| RealDriver
DriverInterface -.->|Local Development| MockDriver
```
### 2.1 Descripción de Capas
1. **Capa de Presentación (Zero-Build):** Servida como assets estáticos directamente por Express desde `/public/`. No realiza compilaciones complejas en caliente; utiliza JavaScript Vanilla moderno (módulos ES6) y Tailwind CSS.
2. **Capa de Transporte & Perímetro:** Gestiona el protocolo HTTP. Los middleware interceptan las peticiones para verificar la firma criptográfica de las cookies de sesión, limitar tasas de peticiones anómalas y convalidar entradas estrictas contra ataques de inyección.
3. **Capa de Dominio & Coordinación:** Implementa las reglas de negocio: validación de colisiones de nombres, exclusión de puertos reservados, coordinación del rollback y cálculo de métricas de telemetría.
4. **Capa de Infraestructura & Drivers:** Encapsula la comunicación con el sistema operativo y el sistema de archivos mediante una interfaz polimórfica que abstrae la presencia o ausencia de Apache2.
---
## 3. Patrones de Diseño de Software
### 3.1 Patrón Strategy: Abstracción de Controladores de Apache
Para resolver la discrepancia crítica entre el entorno de desarrollo local (sin Apache2) y el servidor de producción (Ubuntu con Apache2 nativo), se implementa el patrón **Strategy**.
```mermaid
classDiagram
class IApacheDriver {
<>
+createVirtualHost(name: string, template: string) Promise~void~
+enableSite(name: string) Promise~void~
+disableSite(name: string) Promise~void~
+testConfig() Promise~ConfigTestResult~
+reloadApache() Promise~void~
+deleteVirtualHost(name: string) Promise~void~
+listSites() Promise~SiteInfo[]~
+ensureWebDirectory(name: string) Promise~void~
+removeWebDirectory(name: string) Promise~void~
}
class RealApacheDriver {
-sitesAvailablePath: string
-sitesEnabledPath: string
-webRoot: string
-systemUser: string
+createVirtualHost(name, template)
+enableSite(name)
+disableSite(name)
+testConfig()
+reloadApache()
+deleteVirtualHost(name)
+listSites()
+ensureWebDirectory(name)
+removeWebDirectory(name)
-runCommand(bin: string, args: string[])
}
class MockApacheDriver {
-mockRoot: string
-mockAvailable: string
-mockEnabled: string
-mockWww: string
+createVirtualHost(name, template)
+enableSite(name)
+disableSite(name)
+testConfig()
+reloadApache()
+deleteVirtualHost(name)
+listSites()
+ensureWebDirectory(name)
+removeWebDirectory(name)
-simulateSyntaxCheck(content: string)
}
class ApacheDriverFactory {
+getDriver() IApacheDriver
}
IApacheDriver <|.. RealApacheDriver : implements
IApacheDriver <|.. MockApacheDriver : implements
ApacheDriverFactory --> IApacheDriver : instantiates
```
#### Reglas de Selección del Driver:
- `ApacheDriverFactory.getDriver()` evalúa las condiciones de inicio:
1. Si `process.env.MOCK_APACHE === 'true'`, retorna `MockApacheDriver`.
2. Si el binario `apache2ctl` no se encuentra en el `PATH` del sistema, advierte en el log de inicio y retorna `MockApacheDriver`.
3. Si `apache2ctl` está presente y `MOCK_APACHE !== 'true'`, retorna `RealApacheDriver`.
- **Comportamiento de `MockApacheDriver`:**
- Redirige la raíz a `./.tmp/apache2/sites-available/`, `./.tmp/apache2/sites-enabled/` y `./.tmp/www/`.
- Simula `a2ensite` mediante la creación de enlaces simbólicos relativos en el filesystem local.
- Simula `apache2ctl configtest` parseando balanceo básico de tags XML/Apache (`` y ``). Si el contenido del template contiene la palabra `TRIGGER_SYNTAX_ERROR`, simula una falla sintáctica para probar el rollback.
---
## 4. Máquina de Estados del Rollback Atómico
Para garantizar que ningún error en la configuración generada rompa el servidor web de producción (`apache2`), el aprovisionamiento de subdominios se ejecuta como una **transacción compensatoria atómica** modelada mediante una máquina de estados finitos (FSM).
```mermaid
stateDiagram-v2
[*] --> Idle : Solicitud de Creación Recibida
Idle --> ValidatingInput : Validar Regex y Puertos
ValidatingInput --> Rejected : Validación Fallida (HTTP 400)
ValidatingInput --> WritingFileSystem : Validación Exitosa
state "Modo A (Directorio)" as WritingFileSystem {
[*] --> MkdirWeb : Crear /var/www/
MkdirWeb --> WriteIndex : Generar index.html inicial
WriteIndex --> ChmodSgid : sudo chown & chmod 2775
ChmodSgid --> [*]
}
WritingFileSystem --> WritingConf : Directorio Listo o Modo B
WritingConf --> EnablingSite : Escribir sites-available/.conf
EnablingSite --> RunningConfigtest : sudo a2ensite .conf
RunningConfigtest --> SyntaxEvaluator : sudo apache2ctl configtest
state SyntaxEvaluator <>
SyntaxEvaluator --> FinalizingReload : Syntax OK (Código 0)
SyntaxEvaluator --> RollbackCompensation : Syntax Error (Código != 0)
state "Rollback Atómico Compensatorio" as RollbackCompensation {
[*] --> DissiteAction : sudo a2dissite .conf
DissiteAction --> UnlinkConf : rm sites-available/.conf
UnlinkConf --> CleanupFs : Modo A recién creado?
state FsCleanupDecision <>
FsCleanupDecision --> PurgeFolder : Sí -> rm -rf /var/www/
FsCleanupDecision --> SkipPurge : No (Existía previamente)
PurgeFolder --> [*]
SkipPurge --> [*]
}
RollbackCompensation --> AbortedWithError : Rollback Finalizado
AbortedWithError --> [*] : Retornar HTTP 422 {error: stderr}
FinalizingReload --> Completed : sudo systemctl reload apache2
Completed --> [*] : Retornar HTTP 201 Created
```
### 4.1 Especificación de Estados y Acciones Compensatorias
| Estado | Acción Principal | Falla Posible | Acción Compensatoria (Rollback) |
| :--- | :--- | :--- | :--- |
| `ValidatingInput` | Convalidación regex y colisión de puertos. | Formato inválido o puerto en uso. | Ninguna. Rechazar con HTTP 400/409. |
| `WritingFileSystem` | Crear `/var/www/`, `index.html` y fijar SGID `2775`. | Falla de disco o permisos I/O. | Eliminar directorio parcial y abortar. |
| `WritingConf` | Escribir `/etc/apache2/sites-available/.conf`. | Falla de escritura o permisos. | Eliminar carpeta web creada (si aplica). |
| `EnablingSite` | Invocación de `sudo a2ensite .conf`. | Enlace simbólico corrupto. | Eliminar `.conf` y carpeta creada. |
| `RunningConfigtest` | Invocación de `sudo apache2ctl configtest`. | **Sintaxis Inválida de Apache.** | **1.** `sudo a2dissite .conf`
**2.** `rm sites-available/.conf`
**3.** Purgar carpeta `/var/www` si era nueva.
**4.** **NO EJECUTAR RELOAD.** Retornar HTTP 422. |
| `FinalizingReload` | Invocación de `sudo systemctl reload apache2`. | Error interno de daemon. | Notificar alerta crítica del sistema. |
---
## 5. Modelo de Almacenamiento y Persistencia Ligera
Considerando la restricción de **1 GB de RAM**, no se despliegan instancias pesadas de bases de datos adicionales. El almacenamiento de usuarios se modela mediante un repositorio desacoplado que soporta persistencia en un archivo JSON atómico (`users.json`) o SQLite embebido con `better-sqlite3`.
```mermaid
erDiagram
USUARIO {
string id PK "UUID v4"
string username UK "Identificador alfanumérico"
string password_hash "scrypt hash ($N$r$p$salt$hash)"
string role "admin | operator"
string full_name "Nombre legible del operador"
boolean active "Estado de habilitación"
string created_at "ISO 8601 Timestamp"
string updated_at "ISO 8601 Timestamp"
}
SESION {
string session_id PK "Token criptográfico opaco"
string user_id FK "Referencia al usuario autenticado"
string ip_address "Dirección IP remota"
string user_agent "Huella del navegador"
string expires_at "ISO 8601 Timestamp"
}
SUBDOMINIO_CACHE {
string name PK "Nombre subdominio"
string full_domain "FQDN (name.elingejose.com)"
string type "static | proxy"
string target "Ruta de carpeta o puerto"
boolean enabled "Estado en sites-enabled"
boolean protected "Inmutable si es sitio del sistema"
string updated_at "ISO 8601 Timestamp"
}
USUARIO ||--o{ SESION : "inicia"
```
### 5.1 Protocolo de Escritura Atómica en Disco (`atomic-write`)
Para prevenir corrupción del archivo `users.json` ante caídas de alimentación o reinicios forzados de PM2:
1. Se serializa el JSON en memoria.
2. Se escribe en un archivo temporal adyacente: `users.json.tmp.`.
3. Se sincroniza con disco mediante `fs.fsyncSync()`.
4. Se ejecuta una operación de renombre atómico a nivel de kernel: `fs.renameSync('users.json.tmp.', 'users.json')`.
---
## 6. Arquitectura de Interfaz Zero-Build
La interfaz de usuario sigue una arquitectura de Single Page Application (SPA) sin empaquetadores (*bundlers* como Webpack, Vite o Rollup) para asegurar compatibilidad total con la memoria de 1 GB.
```mermaid
flowchart LR
subgraph BrowserClient["Navegador Web del Operador"]
DOM["Document Object Model"]
State["State Manager (Reactive Store en Memoria)"]
EventBus["Vanilla Event Listeners"]
RenderEngine["Template Literals Renderers"]
end
subgraph StaticAssets["Assets Servidos desde /public/"]
IndexHtml["index.html (HTML5 Estructurado)"]
AppJs["app.js (ES6 Módulos Nativos)"]
TailwindCDN["Tailwind CSS CDN (Pre-procesado)"]
end
IndexHtml --> DOM
TailwindCDN --> DOM
AppJs --> State
State --> RenderEngine
RenderEngine --> DOM
DOM --> EventBus
EventBus --> State
```
### 6.1 Principios del Diseño Zero-Build:
1. **Módulos Nativos de ECMAScript (ESM):** Código estructurado en submódulos cargados con `