Servidor Local e Infraestructura

Para que Yastubo Backend funcione correctamente, requiere una infraestructura de servicios coordinada. Se recomienda utilizar Docker Compose para garantizar la coherencia de versiones entre desarrollo y producción.

Servicios de Infraestructura Requeridos

• Base de Datos: PostgreSQL 16+.
• Caché y Colas de Tareas: Redis 7+.
• Worker: Procesador de tareas asíncronas para procesos en segundo plano.

---

Ejecución con Docker Compose (Recomendado)

La forma más eficiente de iniciar todo el ecosistema es mediante el orquestador oficial:

docker compose up -d

Stack de Servicios

• postgres: Base de datos persistente en el puerto 5432.
• redis: Servidor de caché y mensajería en el puerto 6379.
• app: API de FastAPI expuesta en http://localhost:8000.
• worker: Gestor de procesos asíncronos (emails, webhooks de Stripe).

---

Ejecución para Desarrollo (Modo Hot-Reload)

Si planea modificar el código fuente, es preferible ejecutar la infraestructura en Docker y correr la API y el Worker de forma nativa.

1. Iniciar Infraestructura

docker compose up postgres redis -d

2. Ejecutar la API

uv run uvicorn app.main:app --reload --port 8000

3. Ejecutar el Worker

El worker es vital para la sincronización con servicios externos.

uv run python -m arq app.workers.worker.WorkerSettings

---

Análisis Técnico: Tareas Asíncronas

En Yastubo, las operaciones con alta latencia (como la generación de PDFs o la sincronización con CRM) se ejecutan fuera del ciclo de vida de la petición HTTP mediante una arquitectura de Colas de Mensajería.

Arquitectura Fire & Forget

1. La API recibe la petición de emisión.
2. La API registra la intención en la base de datos y publica un mensaje en Redis.
3. La API responde 201 Created de forma inmediata.
4. El Worker consume el mensaje de Redis y ejecuta la tarea de forma asíncrona.

Tip

Para verificar la conectividad de los servicios, consulte el dashboard de salud: curl http://localhost:8000/api/v1/dashboard/health

Verificación de Conectividad

Respuesta esperada:

{
  "status": "healthy",
  "database": "connected",
  "redis": "connected",
  "version": "1.0.0"
}

---

Diagrama de Interacción de la Infraestructura

[FLOW: El cliente envía una petición HTTP a la API. Si se requiere una tarea asíncrona, la API encola el trabajo en Redis. El Worker consume la tarea y la procesa interactuando con PostgreSQL y servicios externos. Finalmente, se actualiza el estado del registro para su consulta posterior por la API.]