# pabloyanez5/joyeria-xavier architecture

> Architecture diagram of the GitHub repository pabloyanez5/joyeria-xavier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pabloyanez5/joyeria-xavier
- Repository: https://github.com/pabloyanez5/joyeria-xavier

## Overview

Joyería Xavier integra atención conversacional por canales Meta, un catálogo con cotizador web y gestión de órdenes para el taller. El flujo principal va del mensaje entrante, por el webhook y el servicio conversacional, hasta la respuesta enviada por el canal; el panel web también permite consultar conversaciones y seguir órdenes. El README documenta además métricas y gestión administrativa. Las conexiones no visibles en los extractos se omiten; las funciones de panel y métricas se incluyen según la documentación y el índice, sin atribuirles llamadas no verificadas.

Main entry points: [`02_codigo_fuente/backend/app/main.py`](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/main.py) (API FastAPI), [`02_codigo_fuente/backend/app/agente/servicio.py`](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/servicio.py) (Servicio conversacional), [`02_codigo_fuente/backend/app/webhook.py`](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/webhook.py) (Webhook Meta), [`02_codigo_fuente/backend/app/db.py`](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/db.py) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Experiencia web"]
  node_web_app["Catálogo y cotizador<br/>[App.jsx]"]
  node_web_chat["Chat web<br/>[Chat.jsx]"]
  node_admin_panel["Panel administrativo<br/>[Panel.jsx]"]
  node_conversations_ui["Conversaciones UI<br/>[Conversaciones.jsx]"]
  node_dashboard_ui["Resumen y tablero<br/>[Tablero.jsx]"]
end

subgraph group_conversational["Atención conversacional"]
  node_meta_webhook["Webhook Meta<br/>[webhook.py]"]
  node_conversation_service["Servicio conversacional<br/>[servicio.py]"]
  node_agent_routes["Rutas del agente<br/>[rutas.py]"]
  node_langchain_agent["Agente LangChain<br/>[lc_agente.py]"]
  node_intent_classifier["Clasificador de intención<br/>[intenciones.py]"]
  node_llm_provider["Proveedor LLM<br/>[llm.py]"]
  node_message_format["Formato saliente<br/>[mensajes.py]"]
  node_meta_sender["Envío Meta<br/>[meta_envio.py]"]
end

subgraph group_commerce["Catálogo y órdenes"]
  node_catalog["Catálogo y cotizador<br/>[catalogo.py]"]
  node_contact["Contacto asesor<br/>[contacto.py]"]
  node_orders["Órdenes de producción<br/>[ordenes.py]"]
end

subgraph group_operations["Datos y operaciones"]
  node_api["API FastAPI<br/>[main.py]"]
  node_customers["Identidad de clientes<br/>[clientes.py]"]
  node_conversations["Conversaciones y mensajes<br/>[conversaciones.py]"]
  node_metrics["Métricas<br/>[metricas.py]"]
  node_models["Modelos de dominio<br/>[models.py]"]
  node_database[("PostgreSQL<br/>[db.py]")]
  node_cache[("Caché identidad<br/>[cache.py]")]
end

node_visitor(("Cliente web"))
node_meta_user(("Cliente Meta"))
node_llm_external{{"Gemini"}}
node_meta_platform{{"Meta Business API"}}

node_visitor -->|"explora"| node_web_app
node_web_app -->|"consulta catálogo"| node_catalog
node_web_app -->|"solicita contacto"| node_contact
node_visitor -->|"conversa"| node_web_chat
node_admin_panel -->|"muestra"| node_conversations_ui
node_admin_panel -->|"muestra"| node_dashboard_ui
node_api -->|"registra rutas"| node_meta_webhook
node_api -->|"registra rutas"| node_catalog
node_api -->|"registra rutas"| node_contact
node_api -->|"registra rutas"| node_agent_routes
node_api -->|"registra rutas"| node_orders
node_api -->|"registra rutas"| node_conversations
node_api -->|"registra rutas"| node_metrics
node_meta_user -.->|"envía mensaje"| node_meta_webhook
node_meta_webhook -->|"procesa entrante"| node_conversation_service
node_conversation_service -->|"identifica cliente"| node_customers
node_conversation_service -->|"clasifica mensaje"| node_intent_classifier
node_conversation_service -->|"genera respuesta"| node_langchain_agent
node_conversation_service -.->|"guarda mensajes"| node_conversations
node_conversation_service -.->|"consulta identidad"| node_cache
node_langchain_agent -.->|"consulta modelo"| node_llm_provider
node_llm_provider -->|"genera texto"| node_llm_external
node_meta_webhook -->|"envía respuesta"| node_meta_sender
node_meta_sender -.->|"publica mensaje"| node_meta_platform
node_meta_sender -->|"formatea salida"| node_message_format
node_catalog -->|"consulta datos"| node_database
node_orders -->|"persiste etapas"| node_database
node_conversations -->|"persiste historial"| node_database
node_customers -->|"consulta y guarda"| node_cache
node_models -->|"define esquema"| node_database

click node_web_app "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/App.jsx"
click node_web_chat "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Chat.jsx"
click node_admin_panel "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Panel.jsx"
click node_conversations_ui "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Conversaciones.jsx"
click node_dashboard_ui "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Tablero.jsx"
click node_api "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/main.py"
click node_meta_webhook "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/webhook.py"
click node_conversation_service "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/servicio.py"
click node_agent_routes "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/rutas.py"
click node_langchain_agent "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/lc_agente.py"
click node_intent_classifier "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/intenciones.py"
click node_llm_provider "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/llm.py"
click node_message_format "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/mensajes.py"
click node_meta_sender "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/meta_envio.py"
click node_catalog "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/catalogo.py"
click node_contact "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/contacto.py"
click node_orders "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/ordenes.py"
click node_customers "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/clientes.py"
click node_conversations "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/conversaciones.py"
click node_metrics "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/metricas.py"
click node_models "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/models.py"
click node_database "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/db.py"
click node_cache "https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/cache.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_app,node_web_chat,node_admin_panel,node_conversations_ui,node_dashboard_ui,node_visitor,node_meta_user toneBlue
class node_meta_webhook,node_conversation_service,node_agent_routes,node_langchain_agent,node_intent_classifier,node_llm_provider,node_message_format,node_meta_sender toneAmber
class node_catalog,node_contact,node_orders,node_meta_platform toneMint
class node_api,node_customers,node_conversations,node_metrics,node_models,node_database,node_cache toneRose
class node_llm_external toneIndigo
```

## Components

### Experiencia web

- [Catálogo y cotizador](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/App.jsx): `02_codigo_fuente/frontend/web/src/App.jsx`
- [Chat web](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Chat.jsx): `02_codigo_fuente/frontend/web/src/Chat.jsx`
- [Panel administrativo](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Panel.jsx): `02_codigo_fuente/frontend/web/src/Panel.jsx`
- [Conversaciones UI](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Conversaciones.jsx): `02_codigo_fuente/frontend/web/src/Conversaciones.jsx`
- [Resumen y tablero](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/frontend/web/src/Tablero.jsx): `02_codigo_fuente/frontend/web/src/Tablero.jsx`

### Atención conversacional

- [Webhook Meta](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/webhook.py): `02_codigo_fuente/backend/app/webhook.py`
- [Servicio conversacional](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/servicio.py): `02_codigo_fuente/backend/app/agente/servicio.py`
- [Rutas del agente](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/rutas.py): `02_codigo_fuente/backend/app/agente/rutas.py`
- [Agente LangChain](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/lc_agente.py): `02_codigo_fuente/backend/app/agente/lc_agente.py`
- [Clasificador de intención](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/intenciones.py): `02_codigo_fuente/backend/app/agente/intenciones.py`
- [Proveedor LLM](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/agente/llm.py): `02_codigo_fuente/backend/app/agente/llm.py`
- [Formato saliente](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/mensajes.py): `02_codigo_fuente/backend/app/mensajes.py`
- [Envío Meta](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/meta_envio.py): `02_codigo_fuente/backend/app/meta_envio.py`

### Catálogo y órdenes

- [Catálogo y cotizador](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/catalogo.py): `02_codigo_fuente/backend/app/catalogo.py`
- [Contacto asesor](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/contacto.py): `02_codigo_fuente/backend/app/contacto.py`
- [Órdenes de producción](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/ordenes.py): `02_codigo_fuente/backend/app/ordenes.py`

### Datos y operaciones

- [API FastAPI](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/main.py): `02_codigo_fuente/backend/app/main.py`
- [Identidad de clientes](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/clientes.py): `02_codigo_fuente/backend/app/clientes.py`
- [Conversaciones y mensajes](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/conversaciones.py): `02_codigo_fuente/backend/app/conversaciones.py`
- [Métricas](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/metricas.py): `02_codigo_fuente/backend/app/metricas.py`
- [Modelos de dominio](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/models.py): `02_codigo_fuente/backend/app/models.py`
- [PostgreSQL](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/db.py): `02_codigo_fuente/backend/app/db.py`
- [Caché identidad](https://github.com/pabloyanez5/joyeria-xavier/blob/main/02_codigo_fuente/backend/app/cache.py): `02_codigo_fuente/backend/app/cache.py`

### Other components

- **Cliente web**
- **Cliente Meta**
- **Gemini**
- **Meta Business API**

## Connections

- Cliente web → Catálogo y cotizador: explora (evidence: `02_codigo_fuente/frontend/web/src/App.jsx`)
- Catálogo y cotizador → Catálogo y cotizador: consulta catálogo (evidence: `02_codigo_fuente/frontend/web/src/App.jsx`)
- Catálogo y cotizador → Contacto asesor: solicita contacto (evidence: `02_codigo_fuente/frontend/web/src/App.jsx`)
- Cliente web → Chat web: conversa (evidence: `02_codigo_fuente/frontend/web/src/Chat.jsx`)
- Panel administrativo → Conversaciones UI: muestra (evidence: `02_codigo_fuente/frontend/web/src/Panel.jsx`)
- Panel administrativo → Resumen y tablero: muestra (evidence: `02_codigo_fuente/frontend/web/src/Panel.jsx`)
- API FastAPI → Webhook Meta: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- API FastAPI → Catálogo y cotizador: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- API FastAPI → Contacto asesor: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- API FastAPI → Rutas del agente: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- API FastAPI → Órdenes de producción: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- API FastAPI → Conversaciones y mensajes: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- API FastAPI → Métricas: registra rutas (evidence: `02_codigo_fuente/backend/app/main.py`)
- Cliente Meta → Webhook Meta: envía mensaje (evidence: `README.md`)
- Webhook Meta → Servicio conversacional: procesa entrante (evidence: `02_codigo_fuente/backend/app/webhook.py`)
- Servicio conversacional → Identidad de clientes: identifica cliente (evidence: `02_codigo_fuente/backend/app/agente/servicio.py`)
- Servicio conversacional → Clasificador de intención: clasifica mensaje (evidence: `02_codigo_fuente/backend/app/agente/servicio.py`)
- Servicio conversacional → Agente LangChain: genera respuesta (evidence: `02_codigo_fuente/backend/app/agente/servicio.py`)
- Servicio conversacional → Conversaciones y mensajes: guarda mensajes
- Servicio conversacional → Caché identidad: consulta identidad (evidence: `02_codigo_fuente/backend/app/agente/servicio.py`)
- Agente LangChain → Proveedor LLM: consulta modelo
- Proveedor LLM → Gemini: genera texto (evidence: `02_codigo_fuente/backend/app/agente/llm.py`)
- Webhook Meta → Envío Meta: envía respuesta (evidence: `02_codigo_fuente/backend/app/webhook.py`)
- Envío Meta → Meta Business API: publica mensaje (evidence: `README.md`)
- Envío Meta → Formato saliente: formatea salida (evidence: `02_codigo_fuente/backend/app/meta_envio.py`)
- Catálogo y cotizador → PostgreSQL: consulta datos (evidence: `02_codigo_fuente/backend/app/catalogo.py`)
- Órdenes de producción → PostgreSQL: persiste etapas (evidence: `02_codigo_fuente/backend/app/ordenes.py`)
- Conversaciones y mensajes → PostgreSQL: persiste historial (evidence: `02_codigo_fuente/backend/app/conversaciones.py`)
- Identidad de clientes → Caché identidad: consulta y guarda (evidence: `02_codigo_fuente/backend/app/clientes.py`)
- Modelos de dominio → PostgreSQL: define esquema (evidence: `02_codigo_fuente/backend/app/models.py`)
