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:

```python
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.

```python
@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:

```python
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:

```python
# 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