Saltar a contenido

Diagrama de arquitectura GENERAL del sistema

Vista de conjunto (C4 niveles 1–3 + flujo dorado) a partir de hechos ya verificados por otros agentes el 2026-10-10. El VPS histórico está dado de baja: el despliegue descrito es la referencia para redesplegar.

1. Vista de sistema (C4 nivel 1)

Cuatro actores rodean una única app (frontend Next.js + backend FastAPI + Postgres) que se apoya en tres proveedores externos: LLM vía proxy OpenAI-compatible, OAuth social y Hub de modelos.

flowchart LR
    subgraph CLIENTE["Zona cliente"]
        COMENSAL["Comensal<br/>(QR · chat · carrito · pago · review)"]
        MANAGER["Manager<br/>(sala · kanban · aprobación)"]
        SUPERADMIN["Super-admin<br/>(bootstrap · bypass)"]
        COCINA["Cocina (implícita)<br/>vía kanban"]
    end
    subgraph APP["Zona app"]
        FE["Frontend<br/>Next.js 16 + React 19 standalone"]
        BE["Backend<br/>FastAPI + SQLAlchemy async + Alembic<br/>16 módulos hexagonales"]
    end
    subgraph DATOS["Zona datos"]
        PG[("Postgres<br/>restaurantes · salas · sesiones<br/>carrito · comandas · pagos<br/>reviews · conversaciones")]
    end
    subgraph EXTERNOS["Proveedores externos"]
        LLM["Proxy LLM OpenAI-compatible<br/>NVIDIA · DeepSeek Flash (recomendado)"]
        OAUTH["Google + Apple<br/>OAuth RS256"]
        HF["Hugging Face Hub<br/>modelos MiniLM kNN"]
    end
    COMENSAL --> FE
    MANAGER --> FE
    SUPERADMIN --> FE
    COCINA -.-> FE
    FE --> BE
    BE --> PG
    BE --> LLM
    BE --> OAUTH
    BE --> HF

Nota: el VPS histórico está dado de baja; este mapa es la referencia para redesplegar sin cambios de arquitectura.

2. Vista de contenedores y despliegue (C4 nivel 2)

Dos navegadores (comensal y manager) entran por un único nginx con TLS que revierte a los upstreams locales 127.0.0.1:3000 (frontend) y 127.0.0.1:8000 (backend uvicorn). Postgres persiste los datos; hay dos trabajos en segundo plano.

flowchart TB
    subgraph NAV["Navegadores"]
        NAVC["Navegador comensal<br/>QR → chat → carrito → pago"]
        NAVM["Navegador manager<br/>sala · kanban · aprobación"]
    end
    NGINX["nginx reverse proxy<br/>TLS · upstreams 127.0.0.1:3000 / 127.0.0.1:8000"]
    subgraph RUNTIME["Contenedores"]
        FE2["frontend<br/>node:20-alpine standalone<br/>puerto 3000"]
        BE2["backend uvicorn<br/>python:3.12-slim + torch CPU<br/>puerto 8000"]
        PG2[("postgres:15-alpine<br/>datos transaccionales")]
    end
    subgraph VOL["Volúmenes"]
        HFCACHE["hf-cache<br/>modelos MiniLM"]
        PGDATA["pgdata<br/>datos postgres"]
    end
    subgraph JOBS["Trabajos en segundo plano"]
        WORKER["worker recompute-recs<br/>recomendaciones"]
        LIFECYCLE["lifecycle background 60s<br/>sesiones y sala"]
    end
    NAVC --> NGINX
    NAVM --> NGINX
    NGINX --> FE2
    NGINX --> BE2
    FE2 --> BE2
    BE2 --> PG2
    BE2 --- HFCACHE
    PG2 --- PGDATA
    WORKER --> PG2
    LIFECYCLE --> BE2

Nota: VPS dado de baja; los nombres de imagen y puertos son los de la referencia de redespliegue.

3. Vista de componentes backend (C4 nivel 3 simplificada)

Los routers delegan en casos de uso hexagonales; el dominio no conoce la infraestructura. El bus de eventos conecta los 16 módulos sin imports cruzados. Dos seams aíslan lo variable: el dispatcher de modo de chat (con fail-open a legacy) y los gateways de pago y facturación.

flowchart TB
    subgraph IFACE["Capa interface"]
        ROUTERS["Routers FastAPI<br/>auth · session · chat · cart<br/>comanda · payment · manager…"]
        SSE["SSE doble canal<br/>session:{token} · manager:{restaurant_id}<br/>+ stream de chat"]
    end
    subgraph APP3["Capa application"]
        UC["Casos de uso<br/>sesión · carrito · comanda<br/>pago · review · sala"]
        DISPATCH["ModeDispatchingChatAiResponder<br/>seam por restaurants.chat_mode<br/>fail-open a legacy"]
        LEGACY["Chat legacy<br/>engine.py congelado"]
        HYBRID["Chat híbrido<br/>TreeInterpreter + hybrid_v1.json<br/>kNN MiniLM + NvidiaLlmClient thinking-off"]
    end
    subgraph DOM["Capa domain"]
        ENT["Entidades y eventos<br/>table_sessions · cart_items<br/>orders · bills · reviews"]
    end
    subgraph INFRA["Capa infrastructure"]
        REPOS["Repos SQLAlchemy async<br/>+ migraciones Alembic"]
        ADAPTERS["Adaptadores externos<br/>LLM proxy · OAuth · HF Hub"]
        PAYGW["Gateways pago / facturación<br/>(pago fake actual)"]
    end
    BUS(["Event bus<br/>puertos y eventos de dominio"])
    ROUTERS --> UC
    ROUTERS --> SSE
    UC --> DISPATCH
    DISPATCH --> LEGACY
    DISPATCH --> HYBRID
    UC --> ENT
    UC --> REPOS
    UC --> PAYGW
    HYBRID --> ADAPTERS
    UC <--> BUS
    BUS <--> ENT
    REPOS --> ENT

Nota: el gateway de facturación figura como seam prevista; el pago real hoy es fake (ver flujo dorado).

4. Flujo extremo a extremo dorado

Del QR al review pasando por el chat híbrido, la comanda con su máquina de estados y el pago con propina; la cocina ve la comanda en el kanban y el manager la sigue por el canal SSE de sala.

sequenceDiagram
    participant C as Comensal
    participant F as Frontend
    participant B as Backend
    participant H as Chat híbrido
    participant P as Postgres
    participant K as Cocina / Kanban
    participant M as Manager
    C->>F: Escanea QR de mesa
    F->>B: Crea/valida sesión (guest_count)
    B->>P: table_sessions (is_new_session)
    B->>F: Sesión + canal SSE session:{token}
    C->>F: Chatea (pregunta carta/alergias)
    F->>B: Stream de chat
    B->>H: ModeDispatchingChatAiResponder<br/>(chat_mode → híbrido, fail-open legacy)
    H->>B: Respuesta + recomendación (kNN + LLM)
    B->>F: content / thinking / recommendation / done
    C->>F: Añade al carrito (extras + comentario)
    F->>B: CartItemCreate
    B->>P: cart_items
    C->>F: Confirma comanda
    F->>B: Crea orden DRAFT
    B->>P: orders + order_lines + course_plan
    B->>K: Orden visible en kanban
    B->>M: SSE manager:{restaurant_id} sala_snapshot
    K->>B: Avanza estados (…→CLOSED)
    B->>M: table_state_changed
    C->>F: Paga (fake) + propina
    F->>B: bills + payments (idempotency)
    B->>P: bills + payments
    C->>F: Deja review
    F->>B: reviews
    B->>P: reviews
    B->>M: silent_table_alert (mesa libre)

Nota: la cocina es un rol implícito (kanban, sin servicio propio) y el pago es fake con idempotencia; la máquina exacta DRAFT→…→CLOSED la detalla diagramas-backend.md.

Notas y puntos a verificar

  • Cocina modelada como actor implícito vía kanban: no hay servicio ni módulo propio verificado.
  • Pago fake con propina e idempotencia: sin pasarela real cableada a fecha de este diagrama.
  • Gateway de facturación: figura como seam prevista, sin implementación verificada.
  • VPS histórico dado de baja: contenedores, imágenes y puertos son referencia de redespliegue.