VoxPopuli Microservices

Plataforma de reportes comunitarios con arquitectura de microservicios usando FastAPI.

Descripción

VoxPopuli es una infraestructura de microservicios que permite a usuarios crear y reportar incidentes en la comunidad, con un sistema de calificación y visibilidad basado en votación comunitaria.

Características principales:

• API de Usuarios: Gestión de usuarios y autenticación (MySQL)
• API de Reportes: Gestión de reportes comunitarios (MongoDB)
• Sistema de calificación de usuarios (0-100)
• Sistema de visibilidad de reportes con shadowban para contenido de baja calidad
• Penalización de usuarios que crean reportes shadowbaneados

Estructura del Proyecto

VoxPopuli_Microservices/
├── src/
│   ├── domain/                          # Modelos de dominio (entidades de negocio)
│   │   ├── users.py                    # Modelo User
│   │   └── reports.py                  # Modelo Report
│   ├── application/                    # Capa de aplicación (use cases)
│   │   ├── ports/                      # Interfaces (abstracciones)
│   │   │   ├── user_repository.py
│   │   │   └── report_repository.py
│   │   └── services/                   # Casos de uso
│   │       ├── user_services.py
│   │       └── report_services.py
│   ├── infrastructure/                 # Capa de infraestructura
│   │   ├── adapters/
│   │   │   └── persistence/            # Implementaciones de repositorios
│   │   │       ├── db.py              # Configuración MySQL
│   │   │       ├── mongodb.py         # Configuración MongoDB
│   │   │       ├── models.py          # Modelos SQLAlchemy
│   │   │       ├── user_repository_sql.py
│   │   │       └── report_repository_mongo.py
│   │   └── api/                        # APIs REST
│   │       ├── users/                  # Microservicio de Usuarios
│   │       │   ├── app.py             # Factory de la app
│   │       │   ├── router.py          # Enrutador principal
│   │       │   ├── users.py           # Endpoints de usuarios
│   │       │   ├── schemas.py         # Esquemas Pydantic
│   │       │   └── root.py            # Endpoints raíz
│   │       └── reports/                # Microservicio de Reportes
│   │           ├── app.py
│   │           ├── router.py
│   │           ├── reports.py
│   │           ├── schemas.py
│   │           └── root.py
│   ├── core/
│   │   └── config.py                  # Configuración de la aplicación
│   └── main.py                         # Punto de entrada principal
├── .env.example                        # Variables de entorno de ejemplo
└── requirements.txt                    # Dependencias de Python

Requisitos

• Python 3.10+
• MySQL 8.0+
• MongoDB 4.4+

Instalación

1. Clonar el repositorio (o extraer los archivos)

2. Crear entorno virtual:

   python -m venv venv
   

3. Activar entorno virtual:

   • En Windows:

     venv\Scripts\activate
     

   • En Linux/Mac:

     source venv/bin/activate
     

4. Instalar dependencias:

   pip install -r requirements.txt
   

5. Configurar variables de entorno:

   cp .env.example .env
   # Editar .env con tus credenciales de MySQL y MongoDB
   

6. Crear base de datos MySQL:

   CREATE DATABASE voxpopuli_users CHARACTER SET utf8mb4;
   

Ejecución

Ejecutar ambos microservicios:

cd src
python main.py

Esto iniciará:

• API de Usuarios: http://localhost:8000
• API de Reportes: http://localhost:8001

Documentación interactiva:

• Usuarios: http://localhost:8000/docs
• Reportes: http://localhost:8001/docs

Endpoints Principales

API de Usuarios (Puerto 8000)

Método	Endpoint	Descripción
POST	/users/	Crear usuario
GET	/users/{user_id}	Obtener usuario por ID
GET	/users/email/{email}	Obtener usuario por email
GET	/users/	Listar todos los usuarios
PUT	/users/{user_id}	Actualizar usuario
DELETE	/users/{user_id}	Eliminar usuario

API de Reportes (Puerto 8001)

Método	Endpoint	Descripción
POST	/reports/	Crear reporte
GET	/reports/{report_id}	Obtener reporte por ID
GET	/reports/user/{user_id}	Obtener reportes de un usuario
GET	/reports/	Listar todos los reportes
GET	/reports/shadowbanned/list	Listar reportes shadowbaneados
PUT	/reports/{report_id}/visibility	Actualizar visibilidad
DELETE	/reports/{report_id}	Eliminar reporte

Modelos de Datos

Usuario (MySQL)

- user_id: int (PK)
- nombre: str
- apellido: str
- email: str (único)
- fecha_nacimiento: datetime
- fecha_creacion: datetime
- calificacion: float (0-100)
- numero_reportes: int
- url_foto_perfil: str (opcional)
- biografia: str (opcional)

Reporte (MongoDB)

- id_reporte: str (UUID)
- id_usuario: int
- tipo_reporte: int (número que representa el tipo)
- descripcion: str
- ubicacion: str (opcional)
- visibilidad: float (0-100, basado en votación comunitaria)
- fecha_creacion: datetime

Arquitectura

La arquitectura sigue el patrón de Arquitectura Limpia (Clean Architecture):

• Domain: Modelos de negocio puros (entidades)
• Application: Lógica de negocio (casos de uso/servicios)
• Infrastructure: Adaptadores para bases de datos y APIs

Esto permite:

• Independencia de frameworks
• Facilidad de testing
• Separación de responsabilidades
• Reutilización de lógica de dominio

Ejemplo de Uso

Crear un usuario:

curl -X POST "http://localhost:8000/users/" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Juan",
    "apellido": "Pérez",
    "email": "juan@example.com",
    "fecha_nacimiento": "1990-01-15T00:00:00",
    "url_foto_perfil": "https://example.com/photo.jpg",
    "biografia": "Usuario de VoxPopuli"
  }'

Crear un reporte:

curl -X POST "http://localhost:8001/reports/" \
  -H "Content-Type: application/json" \
  -d '{
    "id_usuario": 1,
    "tipo_reporte": 1,
    "descripcion": "Bache en la calle principal",
    "ubicacion": "Calle Principal, Cuadra 5"
  }'

Desarrollo

Ejecutar con hot reload:

Edita src/main.py y cambia reload=False a reload=True

Testing:

(Próximamente se añadirán tests unitarios e integración)

Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

Licencia

Este proyecto está bajo la licencia MIT - ver archivo LICENSE para más detalles.

Autor

Desarrollado como parte de la plataforma VoxPopuli para reportes comunitarios.