# drac-09/api_pomodoro architecture

> Architecture diagram of the GitHub repository drac-09/api_pomodoro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drac-09/api_pomodoro
- Repository: https://github.com/drac-09/api_pomodoro

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Cliente
    Cliente["Cliente / Consumidor API<br/>(Postman, Frontend, CLI)"]:::external

    %% Capa de Entrada
    subgraph "Capa de Entrada (API Layer)"
        API["main.py<br/>FastAPI app"]:::api
        Routers["routers/routers.py<br/>Rutas y Endpoints"]:::api
    end

    %% Capa de Lógica de Negocio
    subgraph "Capa de Lógica de Negocio"
        Auth["utils/auth_utils.py<br/>Autenticación y Tokens"]:::business
        Validate["utils/validate.py<br/>Validaciones genéricas"]:::business
    end

    %% Capa de Persistencia
    subgraph "Capa de Persistencia"
        Models["models/models.py<br/>Modelos ORM (SQLAlchemy)"]:::persistence
        DBInit["utils/database.py<br/>Inicialización y Sesión DB"]:::persistence
        SQLSchema["querys/tablas.sql<br/>Esquema SQL"]:::persistence
        SQLInsertType["querys/insert-type.sql<br/>Insert Tipos"]:::persistence
        SQLInsertRules["querys/inserts-rules.sql<br/>Insert Reglas"]:::persistence
    end

    %% Base de Datos
    subgraph "Base de Datos"
        DB["Base de Datos Relacional<br/>(PostgreSQL/MySQL)"]:::db
    end

    %% Infraestructura
    subgraph "Infraestructura / Contenedor"
        Docker["Dockerfile<br/>Imagen de la Aplicación"]:::infra
        Env[".env.example<br/>Variables de Entorno"]:::infra
        Req["requirements.txt<br/>Dependencias"]:::infra
    end

    %% Test Layer
    Tests["test/test_endpoint.py<br/>Pruebas Unitarias"]:::test

    %% Flujo de datos
    Cliente -->|"HTTP Request"| API
    API --> Routers
    Routers -->|"Llama funciones"| Auth
    Routers -->|"Llama funciones"| Validate
    Auth -->|"Opera con ORM"| Models
    Validate -->|"Valida datos"| Models
    Models -->|"Usa sesión"| DBInit
    DBInit -->|"Conexión"| DB
    SQLSchema -->|"Define tabla"| DB
    SQLInsertType -->|"Inserta datos"| DB
    SQLInsertRules -->|"Inserta datos"| DB
    Docker --> API
    Docker --> Routers
    Docker --> Auth
    Docker --> Validate
    Docker --> Models
    Docker --> DBInit
    Env --> Docker
    Req --> Docker
    Tests --> Routers

    %% Click Events
    click API "https://github.com/drac-09/api_pomodoro/blob/main/main.py"
    click Routers "https://github.com/drac-09/api_pomodoro/blob/main/routers/routers.py"
    click Models "https://github.com/drac-09/api_pomodoro/blob/main/models/models.py"
    click SQLSchema "https://github.com/drac-09/api_pomodoro/blob/main/querys/tablas.sql"
    click SQLInsertType "https://github.com/drac-09/api_pomodoro/blob/main/querys/insert-type.sql"
    click SQLInsertRules "https://github.com/drac-09/api_pomodoro/blob/main/querys/inserts-rules.sql"
    click Auth "https://github.com/drac-09/api_pomodoro/blob/main/utils/auth_utils.py"
    click DBInit "https://github.com/drac-09/api_pomodoro/blob/main/utils/database.py"
    click Validate "https://github.com/drac-09/api_pomodoro/blob/main/utils/validate.py"
    click Tests "https://github.com/drac-09/api_pomodoro/blob/main/test/test_endpoint.py"
    click Docker "https://github.com/drac-09/api_pomodoro/tree/main/Dockerfile"
    click Env "https://github.com/drac-09/api_pomodoro/blob/main/.env.example"
    click Req "https://github.com/drac-09/api_pomodoro/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#E0F7FA,stroke:#006064,stroke-width:1px;
    classDef api fill:#BBDEFB,stroke:#0D47A1;
    classDef business fill:#C8E6C9,stroke:#1B5E20;
    classDef persistence fill:#FFE0B2,stroke:#E65100;
    classDef db fill:#FFCCBC,stroke:#BF360C,stroke-width:2px;
    classDef infra fill:#CFD8DC,stroke:#37474F;
    classDef test fill:#E1F5FE,stroke:#0277BD;
```
