ADR 006: Modular workspace structure

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/decisions/006-modular-workspace.md. Edit at the source, not here.

ADR 006: Modular workspace structure

Status

Accepted

Context

SynVirt ha completado los hitos 0 (foundation) y 0.2 (installer TUI) con una estructura plana de crates. Ahora crecerá significativamente con módulos para storage, networking, virtualización, clustering, backups, catálogo, monitoreo, auth, licencia, migrador desde otros hipervisores, IA distribuida con GPU pooling, sistema de updates con rollback ZFS, e internacionalización (i18n) con default en inglés.

Mantener esta estructura plana llevaría a acoplamiento, builds lentos, y dificultad para testing y mantenimiento.

Adicionalmente, el frontend Next.js requiere un toolchain completamente diferente (Node.js, npm, TypeScript) que no debe contaminar el workspace Rust.

Decision

Reorganizar el código Rust en crates/ con un crate por dominio funcional
Crear crates/core con tipos y traits compartidos
Cada módulo es un crate separado que solo depende de core
El daemon orquesta los módulos via dependency injection con traits
El frontend Next.js vive en web/ como proyecto independiente
La comunicación frontend-daemon es exclusivamente HTTP/WebSocket
Default locale es en-US, NUNCA hardcodear strings en código

Rationale

Los módulos pueden desarrollarse, testearse y versionarse de forma independiente
Cambios en un módulo no requieren recompilar todo el workspace
Reemplazar implementaciones no afecta otros módulos
El frontend tiene su propio ciclo de desarrollo sin acoplamiento al backend
Facilita la documentación: un módulo, un doc
Permite escalar el equipo: distintos devs trabajando en distintos módulos
module-update es crítico para seguridad: kernel, CVEs, módulos y language packs deben actualizarse de forma segura con rollback automático
module-i18n con default en-US permite expansión global del producto

Consequences

Positivas:

Arquitectura escalable a largo plazo
Compilación incremental más rápida
Testing aislado por módulo
Documentación clara por dominio
Facilita auditorías de seguridad por módulo
module-update permite mantener el sistema seguro sin downtime en cluster
module-i18n permite vender el producto en múltiples mercados

Negativas:

Más overhead inicial: definir traits antes de implementar
Cuidado con sobre-ingeniería en traits prematuros
Más archivos Cargo.toml para mantener
Refactor inicial requiere mover crates existentes (one-time cost)
Disciplina requerida: NUNCA hardcodear strings, siempre via i18n

Alternatives considered

Monolito en un solo crate: simple pero no escala
Microservicios separados: overkill, complica deployment
Plugin system con dlopen: complejo, problemas de ABI estable
i18n solo en frontend: rompe single source of truth con backend (CLI, installer, API responses)
Hardcodear strings en un idioma: limita mercado, viola estándares de software profesional