API (@tedos/api)
La API es el backend Fastify de TED OS — el hogar del lado del servidor para los endpoints de
producto, la API del Plan Engine, los webhooks de entrada y el servidor MCP. Stack: Fastify +
Drizzle + Postgres + pg-boss (ADR-001). Desplegado en Fly como la app tedos-api.
Qué expone
| Superficie | Rutas | Notas |
|---|---|---|
| API de producto | /projects, /p/:id/* | Detrás de la guardia de auth/tenancy de Clerk. Ver SoR del producto |
| Engine | /engine/* | El motor de última milla — objetivos / jobs / decisión. Ver Engine |
| Plan Engine | /plan/* | La API del grafo del flujo de trabajo + 9 herramientas MCP plan_*. Ver Plan Engine |
| Webhooks | /webhooks/github | Entrada verificada con HMAC (GitHub → grafo; el patrón de ingesta) |
| Health | /healthz | Usado por los health checks de Fly |
División de procesos (web + worker)
Una imagen, dos grupos de procesos de Fly:
| Proceso | Corre | HTTP público |
|---|---|---|
web | Fastify (las rutas de arriba) | sí |
worker | el handler pg-boss + cron (jobs de espejo, jobs de refresco) | no |
El proceso web arranca pg-boss solo para encolar (el webhook lo necesita); el proceso worker
posee el handler/cron — sin doble registro. Ver
Topología de despliegue.
Dos bases de datos (una regla dura)
La API toca dos bases de datos separadas, nunca una:
| Conexión | Base de datos | Dueño | Migraciones |
|---|---|---|---|
| (env BD del flujo de trabajo) | el grafo del flujo de trabajo / Plan Engine (+ tablas pg-boss) | api + Plan Engine | apps/api/drizzle/ |
| (env BD del producto) | el Sistema de Registro del producto (esquema product) | @tedos/domain | packages/domain/drizzle/ |
Un único comando de release corre ambos conjuntos de migraciones antes de que cualquier máquina nueva sirva tráfico, y aborta (fail-closed) si la variable de entorno de conexión de cualquiera de las bases de datos no está definida. Las dos bases de datos son lógicamente separadas — los datos de tenant/producto nunca deben entrar a la BD del grafo. Ver Decisiones (ADR-006).
La configuración de la API (conexiones de base de datos, claves de Clerk, la capa de modelo, el token de GitHub) vive en variables de entorno. Esta documentación se refiere a esas variables solo por su nombre y nunca incluye sus valores.
El contrato compartido
La API y el admin importan ambos el contrato congelado @tedos/shared (zod-como-fuente
- tipos TypeScript inferidos), así que las formas request/response coinciden por construcción.
La capa de modelo
El provider de modelo del motor se selecciona por entorno: un modelo local (Ollama), un vLLM hosteado (compatible con OpenAI) o un mock determinista sin red. Ver Engine.