Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
69 lines (55 loc) · 3.92 KB

ARCHITECTURE.md

File metadata and controls

69 lines (55 loc) · 3.92 KB
Raw

🏗 Architecture

Overview

Command Center / Vault está construido siguiendo un patrón de diseño arquitectónico en 3 Capas Estrictas (Separation of Concerns - SoC) sobre Vanilla JavaScript moderno (ES Modules) y Vite 8.

La arquitectura elimina la complejidad y el peso de frameworks pesados para ofrecer un tiempo de carga y ejecución en milisegundos, al tiempo que mantiene una estructura modular de nivel empresarial para gestionar el estado, la interfaz y las integraciones de Inteligencia Artificial.

🧱 Arquitectura en 3 Capas Desacopladas

       [ Eventos del DOM / Usuario ]
                     │
                     ▼
       ┌──────────────────────────┐
       │     Controllers Layer    │  (Event Binding & Dispatching)
       │    src/controllers/*.js  │
       └─────────────┬────────────┘
                     │  Delegación de Estado y Negocio
                     ▼
       ┌──────────────────────────┐
       │      Services Layer      │  (Lógica de Negocio Pura)
       │     src/services/*.js    │
       └─────────────┬────────────┘
                     │  Resultado / Cambio de Estado
         ┌───────────┴───────────┐
         ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│    UI Layer     │     │   AI Adapters   │
│ src/ui/*.ui.js  │     │ src/services/ai │
└─────────────────┘     └─────────────────┘

1. Controladores Livianos (src/controllers/)

Los archivos en controllers/ actúan exclusivamente como coordinadores entre la interfaz del usuario y los servicios:

  • Capturan eventos del DOM (clics, ingresos de texto, arrastre de elementos).
  • Extraen parámetros e invocan métodos del servicio correspondiente.
  • Instruyen a la capa ui/ sobre cuándo actualizar la vista o emitir notificaciones (Toasts).
  • Regla estricta: Ningún controlador manipula directamente el almacenamiento local ni realiza cálculos de validación.

2. Capa de Servicios de Negocio (src/services/)

Contiene el núcleo de reglas de negocio y transacciones de estado de la aplicación:

  • vault/vault-crud.service.js: Gestión inmutable del alta, edición y baja de baúles y comandos personalizados.
  • vault/vault-drag-drop.service.js: Lógica matemática de reordenamiento de elementos.
  • vault/vault-import-export.service.js: Validación de esquemas JSON, mezcla de datos importados y generación del archivo de rescate (rollbackData).
  • git.service.js: Validación de convenciones de ramas de Git.

3. Capa de UI Desacoplada (src/ui/)

Responsable de manipular el árbol DOM y renderizar componentes visuales:

  • Renderiza tarjetas de comandos, modales, barras de búsqueda y menús.
  • No almacena estado de negocio.

🤖 Patrón de Adaptadores de Inteligencia Artificial (src/services/ai/)

Para integrar asistencia de Inteligencia Artificial sin acoplar el código a una API externa, el sistema implementa un Patrón Adaptador / Factory:

graph TD
    Client[AI Factory / Orquestador] --> Ollama[OllamaService (Local AI)]
    Client --> OpenAI[OpenAIService (Cloud AI)]
    Client --> Gemini[GeminiService (Cloud AI)]
Loading
  • ai.service.js: Actúa como Factory, determinando en tiempo de ejecución qué proveedor usar según la configuración del usuario.
  • Adaptadores Intercambiables: Cada servicio de IA implementa el mismo contrato de entrada/salida, permitiendo cambiar de un modelo local privado en Ollama a un modelo cloud como Gemini de forma transparente.