Added everything

ARCHITECTURE.md

@@ -0,0 +1,247 @@
+# 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