Mapa de la plataforma

TED OS es un monorepo pnpm + Turborepo. Los workspaces viven bajo apps/* y packages/*; cada paquete compartido se publica bajo el scope @tedos/*. Las apps dependen de los paquetes; los paquetes nunca dependen de las apps.

Apps

App	Paquete	Qué es
admin	@tedos/admin	El admin de dos niveles del operador (plataforma + contexto de proyecto). Next.js en Vercel. → admin
console	@tedos/console	La consola superadmin / interna del operador (console.tuempresa.digital). → console
comprender	(apps/clients/comprender)	La primera instancia white-label de cliente — tenant #1. → comprender
api	@tedos/api	La API Fastify: endpoints de producto, la API del Plan Engine, webhooks, MCP. En Fly. → api
claude-kit-docs	@tedos/claude-kit-docs	Este sitio (docs.tuempresa.digital), protegido por Clerk.
desktop	@tedos/desktop	Un shell de escritorio Tauri — en pausa.

Paquetes

Paquete	Rol
@tedos/auth	Cableado Clerk reutilizable (CSP + middleware) adoptado por las apps de cliente. → Auth
@tedos/domain	El Sistema de Registro del producto (Drizzle/Postgres). → SoR del producto
@tedos/db	El esquema + migraciones del grafo del Plan Engine. → Plan Engine
@tedos/engine	El orquestador de tareas de última milla, agnóstico al modelo, + conectores. → Engine
@tedos/shared	El contrato congelado entre apps (zod-como-fuente + tipos inferidos) compartido por la API y el admin.
@tedos/admin-ui	El sistema de diseño del admin — tokens, shell, components/ui, vistas de pantalla compartidas. → Sistema de diseño
@tedos/ui	La base neutral (paleta + escala tipográfica), agnóstica a iconos y acento.
@tedos/claude-kit-plugin	El plugin empaquetado de claude-kit. → claude-kit

Fronteras del monorepo (reglas duras)

• Sin acceso entre workspaces. Importa otro workspace solo por su nombre @tedos/* — nunca con una ruta relativa a un hermano.
• Dirección de dependencia: las apps dependen de los paquetes; los paquetes nunca de las apps.
• Un workspace por concern. Si lo necesitan 2+ workspaces → extrae un paquete @tedos/*.
• Base vs. skin. @tedos/ui es neutral; el matiz + los iconos de cada superficie viven en su skin (p. ej. @tedos/admin-ui lleva el Cian + HugeIcons del admin). Ver Alcance de color.

La separación de las dos bases de datos

La regla arquitectónica más importante: los datos del flujo de trabajo y los datos de cliente/producto son bases de datos separadas y nunca comparten tablas.

                      un clúster Fly Managed Postgres (hoy)
        ┌──────────────────────────┬──────────────────────────┐
        │  esquema plan            │  esquema product          │
        │  (grafo Plan Engine)     │  (SoR producto, por cli.) │
        │  NUESTROS planes/tareas  │  datos de LOS CLIENTES     │
        │  → corpus de trazas      │  → nunca entra al corpus  │
        └──────────────────────────┴──────────────────────────┘

Ambos esquemas comparten hoy un clúster (un compromiso documentado — aún no hay datos reales de tenant) con una ruta de actualización registrada hacia un clúster dedicado antes de volumen real de PII de tenant. Ver Plan Engine y SoR del producto.

A dónde ir después

• El grafo del flujo de trabajo → Plan Engine
• Los datos de cliente/producto → Sistema de Registro del producto
• Datos, memoria y el futuro asistente por cliente → Datos, memoria y asistente
• El orquestador de tareas → Engine
• El razonamiento detrás de todo → Decisiones (ADRs)