How drac-09/api_pomodoro works
Identificación del proyecto y su propósito
• Se trata de una API REST desarrollada en Python con FastAPI.
• Su función es exponer rutas para gestionar usuarios, sesiones y reglas de Pomodoro, interactuando con una base de datos relacional mediante SQLAlchemy.
• Está diseñada para ser modular, escalable y contener pruebas unitarias, además de empaquetarse en un contenedor Docker.
Análisis de la estructura de ficheros
• En la raíz tenemos:
• main.py: punto de entrada de FastAPI (configuración de app, inclusión de rutas, arranque).
• Dockerfile, requirements.txt, .env.example: despliegue y dependencias.
• release.txt: notas de versión.
• Directorios clave:
• routers/routers.py: define endpoints y asocia cada ruta a un controlador.
• models/models.py: clases ORM SQLAlchemy que representan tablas (tbl_users, tbl_sessions, tbl_pomodoro_rules, tbl_pomodoro_types, tbl_pause_tracking).
• querys/: scripts SQL (tablas.sql, inserts) para crear esquemas y poblar datos.
• utils/:
– auth_utils.py: generación/verificación de tokens, lógica de autenticación.
– database.py: inicialización de la sesión de SQLAlchemy, conexión a DB.
– validate.py: validaciones genéricas.
• test/test_endpoint.py: pruebas unitarias que simulan flujos completos de la API.
Insights del README
• Stack tecnológico: FastAPI, SQLAlchemy, Docker.
• Arquitectura en capas: rutas/controladores → capa de servicios/utilerías → capa de acceso a datos.
• Módulos independientes para autenticación, base de datos y validaciones.
• Scripts SQL independientes para la creación de tablas y datos de muestra.
Cómo crear el diagrama de arquitectura (formato vertical)
a. Componentes principales (de arriba abajo):
1. Cliente / Consumidor de API
• Herramienta HTTP (Postman, Frontend, CLI)
2. Capa de Entrada (API Layer)
• main.py (FastAPI app)
• routers/routers.py (endpoints, rutas)
3. Capa de Lógica de Negocio
• Controladores (funciones dentro de routers)
• auth_utils.py (token, verificación)
• validate.py (reglas de validación)
4. Capa de Persistencia
• models/models.py (clases ORM)
• utils/database.py (sesión, engine)
• querys/*.sql (esquemas y datos)
5. Base de Datos
• PostgreSQL / MySQL (o la que elijas)
6. Infraestructura / Contenedor
• Dockerfile (imagen de la aplicación)
b. Relación e interacción
• Flecha: Cliente → FastAPI (main)
• FastAPI → routers → controladores → servicios/utilities → capa ORM → Base de datos
• Base de datos ↔ SQLAlchemy (sesión abierta)
• Docker empaqueta desde main.py hasta dependencias para desplegar todo el stack.
c. Patrones y principios
• Arquitectura en capas (separación de responsabilidades).
• Modularidad: cada carpeta gestiona un propósito único.
• Inyección de dependencias de FastAPI para sesiones de DB.
• Test-Driven Development (pruebas unitarias en test/).
d. Tecnologías clave
• Python 3.x, FastAPI, Uvicorn
• SQLAlchemy ORM, motores SQL definidos en querys/
• Docker para contenedor
• Pytest (o similar) para pruebas.
Guía de estilo para el diagrama vertical
• Disponer los componentes en columnas o bloques apilados de arriba abajo.
• Personalizar colores para distinguir capas:
• Azul claro para API Layer
• Verde para Lógica de negocio
• Naranja para Persistencia
• Gris para Infraestructura
• Usar formas:
• Rectángulos para servicios internos
• Nubes o usuarios para clientes externos
Elementos imprescindibles
• Etiquetas claras con nombre y función de cada componente.
• Flechas direccionales que indiquen flujo de datos (requests, responses).
• Leyenda o nota explicativa de colores/formas.
• Si es posible, anotar puertos o URLs base (por ejemplo: localhost:8000).
Con esta guía detallada en vertical, el diagrama reflejará con precisión la modularidad, los flujos de interacción y las tecnologías de tu proyecto FastAPI. Mantén siempre actualizada la vista si cambian rutas, modelos o se añaden nuevos servicios.