Cómo funciona BEE por dentro.

Dos aplicaciones, un contrato

BEE es un monorepo con dos aplicaciones que no comparten código y se despliegan por separado. Se hablan únicamente por HTTP, con una API versionada. Esa frontera es deliberada: el cerebro tiene que sobrevivir a una reescritura completa del frontend.

apps/
├── api/    FastAPI · SQLModel · PostgreSQL · Alembic
└── web/    Next.js (App Router) · TypeScript · Tailwind · shadcn/ui

En producción son dos proyectos distintos del mismo proveedor. El frontend conoce al backend por una sola variable (NEXT_PUBLIC_API_URL) y nada más; el backend no sabe que el frontend existe, salvo por la lista de orígenes que acepta en CORS.

Nunca los fusiones en un solo despliegue. La independencia es la que permite cambiar el frontend sin tocar el motor, y escalarlos por separado cuando uno de los dos lo pida antes que el otro.

Lenguajes y piezas

Nada exótico y nada por moda: cada elección resuelve un problema concreto y se puede sustituir sin arrastrar al resto.

Las cuatro capas del backend

El backend es estrictamente por capas y la dependencia siempre apunta hacia adentro. Una capa puede llamar a la de abajo, nunca a la de arriba.

api/           rutas HTTP: validan, autentican, delegan. Cero lógica de negocio.
  ↓
services/      el cerebro: puntuación, estrategias, permisos, integraciones.
  ↓
repositories/  el acceso a datos: consultas, filtros por organización.
  ↓
models/        las tablas SQLModel y sus invariantes.

La regla práctica: si una función de api/ tiene un if que decide algo de negocio, está en la capa equivocada. Y si un servicio escribe un select() a mano en vez de pedirlo a un repositorio, se saltó la capa que garantiza el filtro por organización.

El camino de una señal

Es el recorrido central del producto. Todo lo demás cuelga de aquí.

1. 1Llega un webhook firmado a POST /api/v1/signals/webhook. Se verifica la firma HMAC del emisor y se resuelve el tenant — nada entra sin organización.
2. 2El motor pasa la señal por todos sus analizadores aplicables y agrega sus veredictos en un score.
3. 3La señal se persiste, y si el puntaje califica nace una oportunidad con su ventana de compra y su estrategia: argumento, canal y momento. Respuesta 201.
4. 4Los proveedores externos entran por otra puerta, POST /api/v1/webhooks/receive: esa responde 202 Accepted en milisegundos y encola el enriquecimiento, para no hacer esperar al emisor por una llamada a un tercero.
5. 5El trabajo encolado lo drena un cron cada minuto (ver la sección de trabajos en segundo plano).
6. 6El resultado del cierre —ganado o perdido— vuelve al sistema y ajusta la siguiente jugada.

Las dos puertas son distintas a propósito: /signals/webhook hace el trabajo y contesta 201 con el resultado; /webhooks/receive promete y encola. El 202 de la segunda dice «aceptada», no «procesada» — lo que la hace real es la cola durable de la sección siguiente.

El punto de extensión: analizadores

Los tipos de señal cambian constantemente, así que el motor no los conoce: los descubre. Un analizador es una clase con un decorador, y agregarlo no obliga a tocar ninguna otra parte del sistema.

from app.services.signal_engine.analyzers.base import register_analyzer

@register_analyzer
class MiAnalizador(SignalAnalyzer):
    signal_types = ("mi_tipo",)

    def analyze(self, signal: Signal) -> AnalysisResult:
        ...  # devuelve score, etiquetas y razones

Hoy hay once registrados: financiación, contrataciones, adopción de tecnología, expansión de franquicias, fusiones y adquisiciones, licitaciones públicas, cambios regulatorios, subvenciones, comportamiento, un respaldo genérico y uno basado en LLM.

El analizador de LLM es opcional. Con AI_PROVIDER=none —el valor por defecto— BEE funciona entero con reglas: cero costo, cero latencia externa y ninguna dependencia de un proveedor.

Multi-tenant desde la primera migración

Toda tabla con datos de cliente lleva organization_id, y las 39 que lo llevan tienen un índice encabezado por esa columna desde la migración que crea la tabla.

El aislamiento no se confía a cada consulta: vive en helpers compartidos (scope_to_organization, scope_by_organization_id, get_visible_user_ids). Una consulta que se salte esos helpers es un bug de seguridad, no un atajo.

Regla dura del repositorio: ningún endpoint ni consulta nueva sobre datos de una organización se escribe sin pasar por esos helpers.

Autenticación

BEE no usa Supabase ni ningún proveedor de identidad. La sesión es un JWT propio firmado por el backend.

• El token lleva lo mínimo: id del usuario, id de la organización, rol y expiración.
• En cada petición, get_current_user recarga el usuario de la base y revalida rol e is_active. Desactivar a alguien corta su acceso de inmediato, aunque su token siga vigente.
• El registro crea la organización y su primer usuario OWNER en una sola transacción; el correo es único a nivel global.
• Hay un segundo secreto independiente (API_SECRET_KEY) para llamadas de servicio a servicio, y un tercero (SUPPORT_ADMIN_SECRET) para dos herramientas internas. Filtrar uno no compromete a los otros.

Middleware: el orden importa

Starlette inserta cada middleware al frente de la pila, así que el último registrado es el más externo. En BEE el orden está elegido, no heredado:

CORS                  ← el más externo: contesta los preflight OPTIONS
  └ UnhandledError    ← convierte una excepción en un 500 con JSON
     └ RateLimit      ← por IP, antes de pedir la llave
        └ APIKey      ← exige X-API-Key salvo en las rutas públicas
           └ Security ← cabeceras en toda respuesta, errores incluidos

CORS va afuera porque el navegador nunca manda cabeceras propias en un preflight: si la llave de API se evaluara primero, todo preflight moriría con un 401 y el navegador jamás enviaría la petición real. Y el límite por IP va antes de la llave para que un cliente que martillea con llaves inválidas también se frene, en vez de recibir 401 gratis para siempre.

Trabajos en segundo plano

Esta es la parte que más cuidado pide en un despliegue serverless, y la que más fácil se rompe en silencio.

Sin Redis, encolar significa una asyncio.Queue dentro del proceso. En un servidor de siempre eso está bien; en una función serverless, cuando la instancia se congela, el trabajo encolado desaparece — y el webhook ya respondió 202.

Con Redis, la cola es durable y la drena un cron cada minuto. Un trabajo que falla se reprograma con retroceso exponencial hasta agotar sus reintentos, y de ahí pasa a una cola de mensajes muertos que se puede inspeccionar y reprocesar.

Un aviso ganado a golpes: enciende Redis para colas y límites, pero deja el stream de notificaciones apagado en serverless. Cada pestaña abierta sostiene una función durante 60 segundos en bucle, y eso se paga por segundo.

Esquema y migraciones

44 tablas y 52 revisiones de Alembic. En producción jamás corre create_all(): el arranque compara la revisión de la base con la que espera el código y lo grita en el log si no coinciden, y /api/v1/ready responde 503 mientras haya desfase.

Las migraciones se aplican solas en cada push que toque migraciones o modelos. Si falta el secreto de la base, el paso falla — no avisa y sigue.

Esa última frase es una cicatriz. El paso salía con éxito cuando faltaba el secreto, mostraba palomita verde, y la base se quedó 26 revisiones atrás hasta que un login empezó a fallar. Un paso que puede no hacer nada debe fallar.

Frontend

• App Router con componentes de servidor por defecto. "use client" solo donde hay estado o eventos, y cuanto más abajo del árbol, mejor.
• Los tipos de dominio viven en src/types/domain.ts, espejados a mano desde los esquemas del backend. Cuando cambia un lado, se cambia el otro.
• El sandbox público (/probar) no llama a la API: lee y escribe un almacén de demostración en el navegador, sembrado desde datos de ejemplo. Por eso funciona sin cuenta y sin backend.
• El sistema de diseño manda: todo el color sale de tokens BEE, un tono por caja a tres intensidades, verde solo donde se habla de dinero cerrado, y ningún texto ni icono coloreado.
• Las gráficas son propias y miden su caja: ninguna caja queda con espacio en blanco ni se deforma con datos largos.

Pruebas y cómo correrlo

La suite del backend son 1277 pruebas y es hermética: corre sobre SQLite en memoria, sin Postgres, sin Redis y sin red. Se ejecuta entera en un par de minutos, y ahí se ha atrapado la mayoría de las regresiones de este proyecto.

# Backend
cd apps/api
uv venv .venv && source .venv/bin/activate
uv pip install -r requirements-dev.txt
pytest                      # 1277 pruebas, sin servicios externos
ruff check app tests
uvicorn app.main:app --reload

# Frontend
cd apps/web
pnpm install
pnpm dev                    # http://localhost:3000

# Todo junto: Postgres + Redis + migraciones + API + cron
docker compose up --build