VoxPopuli/ARCHITECTURE.md

Arquitectura de VoxPopuli Microservices

Patrones Arquitectónicos Usados

1. Clean Architecture (Arquitectura Limpia)

La aplicación está organizada en capas independientes:

┌─────────────────────────────────────────────────────────┐
│                    API REST (FastAPI)                    │
│         Infraestructura API (HTTP Handlers)              │
├─────────────────────────────────────────────────────────┤
│              Application Layer (Servicios)               │
│  - Use Cases / Application Services                      │
│  - Lógica de negocio de la aplicación                   │
├─────────────────────────────────────────────────────────┤
│                  Domain Layer (Dominio)                  │
│  - Entidades de negocio puras                           │
│  - Reglas de negocio independientes                     │
├─────────────────────────────────────────────────────────┤
│            Infrastructure Layer (Infraestructura)        │
│  - Adaptadores (Repositorios)                           │
│  - Acceso a Datos (MySQL, MongoDB)                      │
└─────────────────────────────────────────────────────────┘

2. Microservicios

Dos microservicios independientes:

• Usuarios API (Puerto 8000) - Gestión de usuarios y credenciales
• Reportes API (Puerto 8001) - Gestión de reportes comunitarios

Cada microservicio:

• Tiene su propia base de datos
• Es escalable independientemente
• Se puede desplegar por separado
• Expone su propia API REST

3. Patrón Repository

Abstracción para acceso a datos:

┌──────────────────┐
│  Service Layer   │
└────────┬─────────┘
         │ depends on
         ▼
┌──────────────────────────┐
│   Port (Interface)       │
│  UserRepository          │
│  ReportRepository        │
└────────┬─────────────────┘
         │ implemented by
         ▼
┌──────────────────────────┐
│   Concrete Adapters      │
│  UserRepositorySQL       │
│  ReportRepositoryMongo   │
└──────────────────────────┘

Beneficios:

• Independencia de la implementación de BD
• Fácil de testear (usar mocks)
• Reutilizable en diferentes contextos

4. Inversión de Dependencias (Dependency Inversion)

Los servicios dependen de abstracciones (interfaces), no de implementaciones concretas:

class CreateUser:
    def __init__(self, repo: UserRepository):  # Depende de interfaz
        self.repo = repo

# Puede usar cualquier implementación de UserRepository
service = CreateUser(UserRepositorySQL())      # Implementación SQL
# o
service = CreateUser(UserRepositoryMock())     # Para testing

Flujo de Solicitud

Crear Usuario:

1. HTTP POST /users/
   └─> FastAPI Handler
       └─> CreateUser Use Case
           └─> UserRepository.save()
               └─> UserRepositorySQL
                   └─> SQLAlchemy
                       └─> MySQL Database

Crear Reporte:

1. HTTP POST /reports/
   └─> FastAPI Handler
       └─> CreateReport Use Case
           └─> ReportRepository.save()
           └─> UserRepository.increment_reports()
               └─> ReportRepositoryMongo
               └─> UserRepositorySQL
                   └─> MongoDB
                   └─> MySQL

Capas Detalladas

Domain Layer (src/domain/)

Entidades puras de negocio:

• User: Representa un usuario del sistema
• Report: Representa un reporte comunitario

No tienen dependencias externas. Solo representan conceptos de negocio.

@dataclass
class User:
    user_id: int
    nombre: str
    email: str
    # ... más campos

Application Layer (src/application/)

Use Cases y Servicios:

Ports (Interfaces):

• UserRepository: Contrato para acceso a datos de usuarios
• ReportRepository: Contrato para acceso a datos de reportes

Services (Use Cases):

• CreateUser, GetUserById, UpdateUser, DeleteUser
• CreateReport, GetReportById, UpdateReportVisibility

Contienen la lógica de negocio:

class CreateReport:
    def execute(self, id_usuario, tipo_reporte, ...):
        # 1. Validar que usuario existe
        user = self.user_repo.find_by_id(id_usuario)
        
        # 2. Crear reporte
        report = Report(...)
        
        # 3. Guardar en BD
        self.repo.save(report)
        
        # 4. Actualizar contador de usuario
        self.user_repo.increment_reports(id_usuario)

Infrastructure Layer (src/infrastructure/)

Persistence Adapters:

user_repository_sql.py:

• Implementa UserRepository usando SQLAlchemy
• Convierte entre modelo de dominio y modelo de BD

report_repository_mongo.py:

• Implementa ReportRepository usando PyMongo
• Convierte entre modelo de dominio y documento MongoDB

API Handlers:

users/users.py:

• Endpoints HTTP para gestión de usuarios
• Usa esquemas Pydantic para validación

reports/reports.py:

• Endpoints HTTP para gestión de reportes
• Mapeo de solicitudes a use cases

Core Layer (src/core/)

Configuración centralizada:

• Variables de entorno
• Configuración de logging
• Configuración de bases de datos

Testing

La arquitectura facilita el testing:

# Mock Repository para testing
class UserRepositoryMock(UserRepository):
    def __init__(self):
        self.users = {}
    
    def save(self, user):
        self.users[user.user_id] = user
        return user

# Usar en tests
def test_create_user():
    mock_repo = UserRepositoryMock()
    service = CreateUser(mock_repo)
    user = service.execute(...)
    assert mock_repo.users[1] is not None

Escalabilidad

Cada componente puede escalar independientemente:

1. Usuarios API: Escalar horizontal con load balancer
2. Reportes API: Escalar horizontal con load balancer
3. MySQL: Replicación master-slave
4. MongoDB: Sharding automático

Despliegue

Cada microservicio puede desplegarse:

• Docker: Contenedores independientes
• Kubernetes: Pods independientes
• Serverless: Funciones Lambda independientes

Monitoreo

Cada API expone:

• /health - Health check
• /docs - Swagger UI
• Logging estructurado
• Métricas por endpoint

Futuras Mejoras

1. Autenticación: JWT tokens en API
2. Autorización: RBAC (Role-Based Access Control)
3. Rate Limiting: Proteger contra abuso
4. Caché: Redis para datos frecuentes
5. Message Queue: RabbitMQ para comunicación asíncrona
6. Logging Centralizado: ELK Stack
7. Observabilidad: Prometheus + Grafana
8. Tracing: Jaeger para rastreo de solicitudes