backend/
├── app/
│   ├── main.py              # FastAPI app principal
│   ├── core/                # Configuración y utilidades core
│   │   ├── config.py        # Configuración con Pydantic Settings
│   │   ├── database.py      # SQLAlchemy async setup
│   │   ├── security.py      # JWT, hashing, 2FA
│   │   └── logging.py       # Structured logging
│   ├── models/              # Modelos SQLAlchemy
│   │   ├── tenant.py        # Modelo de tenant (multi-tenancy)
│   │   ├── user.py          # Modelo de usuario
│   │   └── ...              # Otros modelos
│   ├── api/                 # API routes
│   │   └── v1/              # API version 1
│   │       ├── router.py    # Router principal
│   │       └── endpoints/   # Endpoints por dominio
│   ├── middleware/          # Custom middleware
│   ├── services/            # Business logic
│   ├── repositories/        # Data access layer
│   ├── schemas/             # Pydantic schemas
│   └── utils/               # Utilidades compartidas
├── tests/                   # Tests unitarios e integración
├── migrations/              # Migraciones Alembic
├── requirements.txt         # Dependencias Python
└── pyproject.toml          # Configuración del proyecto

Características Implementadas

Core

FastAPI app con configuración async
Pydantic Settings para configuración
SQLAlchemy 2.0 async
Structured logging con structlog
JWT authentication con refresh tokens
2FA con TOTP
Multi-tenancy middleware

API

Health checks (/health, /health/detailed)
Authentication endpoints básicos
Middleware de correlation ID y tenant
Error handling centralizado
CORS configurado

Seguridad

Argon2 password hashing
JWT con algoritmos seguros
TOTP 2FA implementation
Validation con Pydantic v2

Quick Start

# Instalar dependencias
pip install -r requirements.txt

# Variables de entorno (copiar desde raíz del proyecto)
cp ../.env.example .env

# Ejecutar en desarrollo
uvicorn app.main:app --reload --port 8000

# O usar Docker
docker-compose up backend

Testing

# Ejecutar tests
pytest

# Con coverage
pytest --cov=app tests/

# Solo tests unitarios
pytest -m "unit"

# Solo tests de integración
pytest -m "integration"

Code Quality

# Linting
ruff check .

# Formateo
black .

# Type checking
mypy .

# Fix automático
ruff check . --fix
black .

Desarrollo

Agregar nuevos endpoints

Crear schema en app/schemas/
Crear endpoint en app/api/v1/endpoints/
Registrar router en app/api/v1/router.py
Agregar tests en tests/

Modelos de base de datos

Crear modelo en app/models/
Importar en app/models/__init__.py
Crear migración: alembic revision --autogenerate -m "descripción"
Aplicar migración: alembic upgrade head

Variables de entorno

Todas las configuraciones están en app/core/config.py usando Pydantic Settings.

Ver .env.example para todas las variables disponibles.

Arquitectura

Clean Architecture

Presentation: FastAPI endpoints y schemas
Application: Services y casos de uso
Domain: Entidades y reglas de negocio
Infrastructure: Repositorios, DB, external APIs

Patrones implementados

Repository pattern para acceso a datos
Dependency injection con FastAPI Depends
Unit of Work para transacciones
Command/Query separation

Monitoring

Structured logging con correlation IDs
Health checks para load balancer
Métricas con Prometheus (TODO)
Error tracking (TODO)

Security Checklist

Password hashing con Argon2
JWT con secret keys seguras
CORS restrictivo
Input validation con Pydantic
SQL injection protection (SQLAlchemy)
Rate limiting (TODO: implementar)
File upload validation (TODO: implementar)
XSS protection (headers en nginx)

Próximos pasos

Implementar repositorios y services
Completar autenticación con base de datos
Agregar endpoints de users y tickets
Implementar rate limiting
Agregar métricas y monitoring
Tests de integración completos