OpenRubberDocks: Anatomía Técnica de una Plataforma de Documentación y Gestión de Proyectos Self-Hosted con Integración Nativa de IA

En el ecosistema actual de herramientas de productividad, los equipos de desarrollo suelen enfrentarse a una disyuntiva incómoda: ceder el control de su base de conocimientos a soluciones SaaS cerradas o conformarse con herramientas self-hosted que separan la documentación técnica de la gestión de tareas y carecen de estándares modernos de interoperabilidad.

OpenRubberDocks nace para resolver esta fricción. Es una plataforma de código abierto, autoalojable (self-hostable), que unifica la edición de documentos basada en bloques, la gestión avanzada de proyectos y una arquitectura lista para agentes de inteligencia artificial mediante el protocolo MCP (Model Context Protocol).

A continuación, exploramos las decisiones de arquitectura, el diseño de software y los componentes técnicos que dan vida a esta plataforma.

1. Visión General de la Arquitectura

El repositorio de OpenRubberDocks está estructurado bajo una separación limpia entre el servidor API (backend/), el cliente web (frontend/) y el conjunto de utilidades de aprovisionamiento automatizado.

Capa / Módulo	Tecnologías y Patrones Clave	Responsabilidad Principal
Backend (`backend/`)	NestJS, TypeScript, TypeORM, Passport (JWT), pnpm	Lógica de dominio modular, cumplimiento del estándar JSON:API, RBAC con alcance (scope), auditoría y servidor MCP.
Frontend (`frontend/`)	React, TypeScript, Vite, TanStack Query (tsq)	Interfaz de usuario con estética brutalista, arquitectura orientada a features, editor de bloques y tableros interactivos.
Infraestructura	Docker, Docker Compose, Scripts CLI (`install.mjs`, `.sh`, `.bat`)	Orquestación de contenedores, validación de variables de entorno y despliegue sin fricción en servidores locales o VPS.

2. Backend: Modularidad Estricta y Estándar JSON:API

El núcleo del servidor está construido sobre NestJS utilizando TypeORM para la capa de persistencia y migraciones estructuradas (src/database/migrations/). En lugar de exponer respuestas REST arbitrarias, toda la comunicación HTTP se rige estrictamente por la especificación JSON:API.

Cumplimiento Automatizado de JSON:API

Para evitar que los controladores y servicios de negocio se contaminen con lógica de formateo, el backend implementa una tubería transversal en src/common/:

Interceptores y Pipes (json-api.interceptor.ts, json-api-deserialize.pipe.ts): Transforman automáticamente las respuestas de las entidades al formato de documento JSON:API (data, attributes, relationships, meta) y deserializan los payloads entrantes antes de que lleguen al controlador.
Filtrado Dinámico Seguro (typeorm-filter.util.ts, json-api-query.decorator.ts): Traduce parámetros de consulta complejos siguiendo el estándar JSON:API directamente a cláusulas seguras de TypeORM.
Manejo de Excepciones (json-api-exception.filter.ts): Captura cualquier error de dominio o validación y lo estandariza bajo la estructura de objetos de error de la especificación.

Control de Acceso Basado en Roles y Alcance (Scoped RBAC)

La seguridad no se limita a un simple rol global. El módulo authorization/ junto con los seeders iniciales (src/database/seeds/rbac/) implementan un sistema de permisos granular (permission.entity.ts, role.entity.ts, user-role-scope.entity.ts):

Mediante los decoradores @RequirePermissions() y @CheckScope() evaluados por PermissionsGuard (src/common/guards/permissions.guard.ts), el sistema valida no solo qué acción intenta realizar un usuario, sino en qué contexto (nivel global vs. un Workspace específico).
Adicionalmente, la migración AddExternalUserRules permite modelar reglas específicas para colaboradores o usuarios externos con vistas restringidas.

Trazabilidad y Auditoría Transparente

En entornos colaborativos, saber quién modificó un recurso es crítico. El módulo audit/ incorpora el interceptor AuditInterceptor (audit.interceptor.ts) acompañado de un sanitizador de datos (audit-sanitizer.util.ts). Cada mutación relevante en la API se registra de forma asíncrona ocultando campos sensibles (como contraseñas o tokens), y ofrece el decorador @SkipAudit() para excluir rutas de lectura o telemetría menor.

3. El Motor de Contenido y Gestión de Proyectos

Dentro de un Workspace (modules/workspace/), convergen los dos pilares funcionales de OpenRubberDocks: la documentación viva y la ejecución de proyectos.

Documentación Basada en Bloques con Historial de Revisiones

El módulo modules/files/ divide la responsabilidad en dos submódulos altamente cohesivos:

File Manager (files/manager/): Administra el ciclo de vida del documento (file.entity.ts), su jerarquía en árbol, estados (file-status.enum.ts) y metadatos visuales.
Block Engine (files/blocks/): Cada documento se compone de unidades atómicas (block.entity.ts) tipificadas (block-type.enum.ts). Soporta operaciones de creación, movimiento posicional (move-block.dto.ts) y sincronización por lotes (sync-blocks.dto.ts).

Tanto los archivos como los bloques individuales cuentan con control de versiones en base de datos (file-revision.entity.ts y block-revision.entity.ts), permitiendo auditar cambios granulares y restaurar estados anteriores sin pérdida de información.

Gestión de Proyectos Polimórfica

El módulo modules/projects/ va mucho más allá de una lista de pendientes tradicional:

Configuración a medida por proyecto: Cada proyecto define sus propios estados (task-status.entity.ts), tipos de tarea (task-type.entity.ts) y propiedades dinámicas personalizadas (task-property-definition.entity.ts).
Grafo de Dependencias y Registro de Tiempo: Las tareas (task.entity.ts) soportan relaciones de dependencia (task-dependency.entity.ts) y bitácoras de tiempo invertido (task-time-log.entity.ts).
Vinculación Directa con Documentación: A través de project-file-link.entity.ts, los documentos técnicos del workspace se enlazan directamente como contexto vivo de cada proyecto.

4. Integración Nativa con Agentes IA vía MCP

Una de las características más diferenciales de OpenRubberDocks es su soporte nativo para el Model Context Protocol (MCP) dentro de backend/src/modules/mcp/ (documentado a fondo en docs/mcp-agent-integration.md).

En lugar de requerir scrapers externos o integraciones frágiles, OpenRubberDocks expone un controlador y servicio MCP dedicados (mcp.controller.ts, mcp.service.ts) protegidos mediante McpAuthGuard. Combinado con el sistema de API Keys (api-keys.service.ts, generables vía interfaz o mediante el comando CLI create-api-key.command.ts), cualquier agente de IA o asistente de código puede autenticarse de forma segura para leer documentación, consultar el estado de las tareas en un proyecto o estructurar nuevos bloques de conocimiento respetando las reglas de permisos del usuario.

5. Frontend: Arquitectura Orientada a Features y Experiencia de Usuario

El cliente web (frontend/) está desarrollado con React y TypeScript, empaquetado con Vite. Su estructura de directorios refleja una separación estricta entre infraestructura transversal (src/core/) y módulos de negocio (src/features/).

Patrón Repository -> Service -> Hook

Para mantener los componentes de React limpios y enfocados exclusivamente en la vista, cada dominio dentro de src/features/ (como admin/, auth/, workspaces/files/, workspaces/projects/) implementa una arquitectura en capas:

Capa HTTP Base (core/http/): Gestiona las peticiones con interceptores dedicados para la renovación transparente de sesiones JWT (auth-refresh.interceptor.ts) y la normalización de payloads JSON:API (json-api.interceptor.ts).
Repositories & Services: Encapsulan las llamadas a los endpoints y la transformación de modelos de dominio.
Custom Hooks con TanStack Query (core/config/tsq/): Hooks especializados (useBlockEditor, useKanbanBoard, useTimeline, useFileRevisions) administran la caché, mutaciones optimistas y sincronización de estado con el servidor.

Interfaz, Editor Multi-Pestaña y Detalles con Personalidad

La experiencia de usuario destaca por su velocidad y atención al detalle técnico:

Edición Fluida: El editor soporta pestañas de documentos simultáneas (DocumentTabsBar.tsx), árbol de páginas colapsable (PageTreeSidebar.tsx), bloques reordenables (SortableBlock.tsx), parseo directo de Markdown (markdown-block.parser.ts), almacenamiento local de borradores (draft-storage.utils.ts), selector de plantillas (TemplateSelectorModal.tsx) y un cajón interactivo para explorar el historial de revisiones (RevisionHistoryDrawer.tsx).
Vistas Múltiples de Proyecto: Los equipos pueden alternar entre un tablero Kanban interactivo (KanbanBoard.tsx), vista tabular de tareas (TasksTable.tsx), cronograma temporal (Timeline en TimelineView.tsx con registro de horas en TimeLogModal.tsx) y una vista dedicada para usuarios externos (ExternalProjectOverview.tsx).
Identidad Visual y “Cliamp Radio”: La interfaz combina componentes de corte brutalista (BrutalistBreadcrumbs.tsx), control declarativo de permisos en UI mediante el componente <Can/> (Can.tsx), soporte de temas personalizables (core/theme/) y un toque único para acompañar las sesiones de programación y escritura: Cliamp Radio (CliampRadio.tsx y CliampSpectrumCanvas.tsx), un reproductor integrado en la aplicación con visualizador de espectro de audio en tiempo real renderizado en HTML5 Canvas.

6. Despliegue Automatizado y Filosofía Self-Hosted

Un proyecto open source autoalojable solo es tan bueno como su facilidad de instalación. OpenRubberDocks incluye soporte completo para contenedores mediante docker-compose.yml y Dockerfile independientes para el frontend y el backend.

Además, en la raíz del proyecto se incluye un instalador multiplataforma interactivo (install.mjs, junto con sus wrappers install.sh para sistemas Unix/Linux y install.bat para Windows) y comandos CLI internos en el backend (launch.command.ts) que guían al administrador en la configuración de variables de entorno, inicialización de la base de datos, ejecución de migraciones y creación de credenciales iniciales en cuestión de segundos.