Arquitectura

Respuesta directa

Cómo encajan Astro, Phoenix, Neon, Oban y los adaptadores de proveedores en la versión alfa actual de TextTree.

Contenido de la página

# Arquitectura

El sitio público y el entorno de ejecución de la aplicación están deliberadamente separados.

## Superficie pública

Astro es responsable de:

- páginas de aterrizaje
- documentación
- blog
- metadatos de SEO, RSS y generación del sitemap

## Superficie de la aplicación

Phoenix es responsable de:

- inicio de sesión y experiencia de usuario autenticada
- `/api/v1/*`
- webhooks firmados de proveedores
- `/mcp/*`

## Estado central

Postgres respaldado por Neon es el sistema de registro para:

- usuarios nativos de Phoenix e identidades de autenticación de TextTree
- cuentas de agentes headless basadas en nombre de usuario
- usuarios y espacios de trabajo
- metadatos heredados de consentimiento/contactos
- supresiones de espacio de trabajo y de campaña
- mensajes
- entradas del libro contable y límites de gasto
- eventos de proveedores
- sesiones de financiamiento
- auditorías de ejecución de MCP

## Responsabilidad de los workers

Oban es responsable de los efectos secundarios y los reintentos.

- los mensajes salientes se encolan antes de la ejecución en el proveedor
- los eventos de proveedores se almacenan antes de la reconciliación
- las rutas de repetición y reintento se mantienen fuera de los controladores y las LiveViews

## Reglas de ejecución

La mensajería saliente sigue una ruta estricta:

1. verificación de supresión del espacio de trabajo
2. reserva de gasto y escritura en el libro contable
3. encolado en Oban
4. ejecución en el proveedor dentro de un worker

Eso mantiene los efectos secundarios externos fuera de los controladores y las LiveViews.

## Reglas de webhooks

Los webhooks de proveedores siguen un límite paralelo:

1. verificación de firma
2. persistencia del evento normalizado
3. detección de duplicados
4. encolado en Oban
5. reconciliación en el estado de mensaje, supresión o financiamiento

## Reglas de MCP

La superficie de MCP es intencionalmente reducida en la versión alfa:

1. salud pública y bootstrap de cuentas headless
2. autenticación con token bearer de TextTree para las rutas de herramientas
3. aplicación de scopes a nivel de ruta
4. verificaciones de registro de servidores y de listas de permitidos
5. controles de cuota y de tiempo de espera
6. registros de auditoría de ejecución persistidos

El bootstrap de cuentas headless a través de `/api/v1/accounts` o `/mcp/accounts` crea
una cuenta de agente con nombre de usuario/contraseña, códigos de respaldo de un solo uso y un token bearer
de TextTree. La limitación del bootstrap almacena una dirección IP con hash y permite solo una
creación de cuenta exitosa por IP cada cinco minutos.

## Límites de proveedores

Los controladores y las LiveViews no llaman a los proveedores directamente.

- las rutas de mensajería se comunican con el contexto de mensajería
- las rutas de financiamiento se comunican con el contexto de financiamiento
- la semántica HTTP específica de cada proveedor se mantiene dentro de los adaptadores de proveedores
- la normalización de webhooks ocurre antes de la reconciliación del estado de negocio

## Restricciones de la versión alfa

Esta arquitectura ya es utilizable, pero sigue siendo intencionalmente incompleta:

- los ADR locales del repositorio capturan la línea base de implementación actual mientras la importación canónica del canvas sigue pendiente
- algunas superficies del producto son solo para operadores y no contratos de API públicos
- las herramientas de MCP se configuran en el servidor, no por tenant
- la documentación describe el contrato alfa implementado, no promesas de una hoja de ruta futura