Saltar al contenido principal

Arquitectura del Backend

Arquitectura detallada del backend de Floutic.

Estructura de Directorios​

/app
 ├── api/v1/endpoints/     # Módulos de endpoints
 │   ├── auth/             # Autenticación (modular)
 │   │   ├── __init__.py   # Router principal
 │   │   ├── registration.py # Registro de usuarios
 │   │   ├── login.py      # Login estándar y seguro
 │   │   ├── session.py    # Refresh, logout, verify
 │   │   ├── email_verification.py # Verificación de email
 │   │   ├── password.py   # Recuperación de contraseña
 │   │   └── roles.py      # Gestión de roles
 │   ├── users.py          # Gestión de usuarios
 │   ├── profiles.py       # Perfiles empresa/experto/admin (incluye subida de imagen y perfiles de admin)
│   └── services/
│       └── profile_image_service.py  # Servicio centralizado para manejo de imágenes de perfil
 │   ├── projects/         # Proyectos y matching (modular)
 │   │   ├── __init__.py   # Router principal
 │   │   ├── listing.py     # Listado de proyectos
 │   │   ├── crud.py       # CRUD básico
 │   │   ├── applications.py # Aplicaciones de expertos
 │   │   ├── selection.py  # Selección de expertos
 │   │   ├── workflow.py   # Validación y curación
 │   │   ├── disputes.py   # Gestión de disputas
 │   │   └── helpers.py    # Funciones auxiliares
 │   ├── chat.py           # Sistema de mensajería
 │   ├── payments.py       # Pagos y escrow
 │   ├── reviews.py        # Reseñas y reputación
 │   ├── milestones.py     # Hitos y entregas
 │   ├── admin/            # Panel administrativo (modular)
 │   │   ├── __init__.py   # Router principal
 │   │   ├── users.py      # Gestión de usuarios
 │   │   ├── projects.py   # Gestión de proyectos
 │   │   ├── payments.py   # Endpoints de pagos (delgados, delegan a PaymentService)
 │   │   ├── disputes.py   # Gestión de disputas
 │   │   ├── metrics.py    # Métricas y dashboard
 │   │   ├── commissions.py # Configuración de comisiones
 │   │   ├── skill_pages.py # Páginas de habilidades
 │   │   ├── exports.py    # Exportación de datos
 │   │   ├── system.py     # Salud del sistema
 │   │   └── helpers.py    # Funciones auxiliares
 │   └── ghl_integration.py # Integración GoHighLevel
 ├── models/               # Modelos de base de datos
 ├── schemas/              # Esquemas Pydantic
 ├── services/             # Servicios especializados
 │   ├── payment_service.py # Lógica de negocio de pagos y escrow
 │   ├── profile_image_service.py # Manejo de imágenes
 │   └── ...               # Otros servicios (Stripe, Email, etc.)
 └── core/                 # Configuración y seguridad

Componentes Principales​

Endpoints​

Los endpoints están organizados por funcionalidad en módulos separados.

Modelos​

Modelos SQLAlchemy que representan las entidades de la base de datos.

Modelo Profile:

  • Soporta múltiples tipos: empresa, experto, admin
  • Campos específicos por tipo de perfil
  • Campos de admin: full_name, team_role, display_order, is_visible_in_team, redes sociales (LinkedIn, Twitter, GitHub, Instagram, TikTok), personal_website
  • Campo común profile_picture para todos los tipos de perfil
  • Campo internal_rating (1.0-5.0) para valoración administrativa de expertos

Modelo InternalRatingHistory:

  • Registra todos los cambios de valoración interna con trazabilidad completa
  • Campos: user_id, profile_id, old_rating, new_rating, reason, changed_by_id, created_at
  • Permite auditar quién cambió la valoración, cuándo y por qué

Schemas​

Esquemas Pydantic para validación de datos de entrada y salida.

Servicios​

Lógica de negocio encapsulada en servicios reutilizables.

ProfileImageService (app/services/profile_image_service.py):

  • Validación robusta de imágenes (tipo, tamaño, extensión)
  • Validación con Pillow para asegurar que el archivo sea realmente una imagen
  • Optimización automática de imágenes (redimensionado, compresión)
  • Normalización centralizada de rutas
  • Funciones para guardar y eliminar imágenes
  • Conversión entre rutas de BD y rutas de archivo físico
  • Generación de nombres de archivo SEO-friendly

PaymentService (app/services/payment_service.py):

  • Gestión centralizada de pagos Escrow
  • Interacción con Stripe Connect (PaymentIntents, Transfers, Refunds)
  • Reglas de negocio críticas: prevención de duplicados, validación de presupuestos
  • Sincronización automática de estados mediante webhooks
  • Gestión de hitos (milestones) relacionada con pagos

Core​

Configuración, seguridad y utilidades compartidas.

Manejo de Fechas (Datetime Utils):

  • app/core/datetime_utils.py provee funciones seguras para manejo de tiempo.
  • now_utc(): Retorna datetime con timezone UTC (para lógica de negocio).
  • now_utc_naive(): Retorna datetime sin timezone (para campos TIMESTAMP WITHOUT TIME ZONE de PostgreSQL).
  • Validación Runtime: Ambas funciones validan que el retorno sea correcto para prevenir errores 500 en producción.

Flujo de Datos​

  1. Request → Endpoint
  2. Validación → Schema Pydantic
  3. Lógica → Service
  4. Persistencia → Model (SQLAlchemy)
  5. Response → Schema Pydantic

Estándares y Limitaciones​

Paginación​

Por defecto, los endpoints de listado (ej. /profiles/experts) están paginados.

  • Límite máximo por página (size): 100 items.
  • Comportamiento si excede: Retorna error 422 Unprocessable Entity.
  • Iteración: Los consumidores deben iterar paginando manualmente si necesitan recuperar todos los registros (ej. generación de sitemaps).

Más Información​