Stack tecnológico¶
Decisión de producto
El stack completo se define desde el inicio porque el proyecto contempla apps nativas iOS y Android, API pública, backoffice operativo, manejo intensivo de imágenes y procesos en background.
Stack completo¶
| Componente | Tecnología | Rol |
|---|---|---|
| Base de datos | PostgreSQL | Fuente principal de verdad — todos los modelos, estados, usuarios, pagos, auditoría |
| Cache / Jobs / Locks | Redis | Cache, rate limiting, OTP, locks para procesos críticos, jobs en background |
| Backend principal | Django + DRF | ORM, modelos, migraciones, admin, auth, gestión de archivos, lógica de negocio |
| API pública | FastAPI | Endpoints consumidos por apps nativas y servicios externos, validaciones Pydantic |
| Almacenamiento | MinIO (S3-compatible) | Fotos de paquetes, documentos KYC, evidencias, comprobantes |
| Mobile iOS | Swift/SwiftUI | App nativa para iOS |
| Mobile Android | Kotlin/Jetpack Compose | App nativa para Android |
Responsabilidades por tecnología¶
Django — Backend y administración¶
- Define modelos y migraciones (fuente de verdad del esquema)
- Panel Django Admin (backoffice operativo)
- ORM principal (todos los modelos del negocio)
- Sistema de autenticación y permisos
- Revisión y aprobación de KYC
- Operación interna
- Gestión de archivos hacia MinIO
- Lógica de negocio: servicios compartidos en core/services/
- Gestión de usuarios, roles y permisos
- Configuración de tarifas, categorías, tutoriales y contenido de aduana
FastAPI — API pública¶
- API consumida por apps iOS y Android
- Endpoints de cliente (registro, prealertas, paquetes, cotizaciones, pagos)
- Validaciones con Pydantic (entrada y salida)
- Documentación OpenAPI automática
- Integraciones externas (webhooks, notificaciones push)
- No define modelos propios — consume la capa de servicios compartida
PostgreSQL — Base de datos¶
- Todos los modelos relacionales
- Estados, usuarios, paquetes, pagos, auditoría
- KYC, referidos, crédito, tarjetas
- Transacciones para operaciones críticas
Redis — Cache, jobs y sincronización¶
1. OTP de teléfono
- Código temporal de 6 dígitos
- Expira en 5 minutos
- Máximo 3 intentos por código
2. Rate limiting
- Login: 5 intentos por minuto
- OTP: 3 solicitudes por minuto
- Recuperación de contraseña: 2 por hora
- Endpoints sensibles: 60 requests/minuto por usuario
3. Cache
- Tarifas activas (TTL: 5 minutos)
- Categorías de producto (TTL: 1 hora)
- Contenido de aduana (TTL: 1 hora)
- Tutoriales publicados (TTL: 1 hora)
4. Locks distribuidos (para procesos críticos)
- Generación de identificador único (evitar duplicados)
- Aplicación de crédito (evitar race conditions)
- Confirmación de pago (evitar doble cargo)
- Consolidación de paquetes (evitar estados inconsistentes)
5. Jobs / tareas en background
- Notificaciones push
- Vencimiento de almacenaje (verificar diario)
- Expiración de crédito
- Recalculo de niveles de red
- Limpieza de archivos vencidos
MinIO — Almacenamiento de archivos¶
Buckets:
- kyc-documents → Documentos KYC (solo acceso interno)
- package-photos → Fotos de paquetes recibidos
- order-evidence → Capturas de órdenes y comprobantes
- inspection-evidence → Fotos/videos de inspecciones
- return-evidence → Evidencias de devoluciones
- user-avatars → Avatares de perfil
- public-content → Contenido público (tutoriales, imágenes)
Archivos KYC nunca públicos
Los documentos KYC, selfies y evidencias nunca deben ser públicos. Acceso solo con URL firmada temporal y con log de auditoría.
Arquitectura de capas¶
Apps iOS/Android/Web
│
▼ HTTPS
FastAPI — API pública
│
▼
Capa de servicios compartidos (core/services/)
│
├──► Django ORM
│ │
│ ├──► Django Admin (backoffice operativo)
│ └──► MinIO (archivos privados)
│
└──► PostgreSQL (modelos, transacciones)
Regla inquebrantable
Django define los modelos y migraciones. FastAPI consume la misma base de datos y la misma capa de servicios. No se duplica lógica de negocio en FastAPI. La inteligencia vive en core/services/, no en views ni endpoints.
Capa de lógica compartida¶
Toda la lógica de negocio vive en servicios importables desde core/services/:
core/
models/ ← Modelos Django (fuente de verdad)
services/ ← Lógica de negocio
package_service.py
kyc_service.py
quote_service.py
payment_service.py
consolidation_service.py
notification_service.py
referral_service.py
credit_service.py
repositories/ ← Acceso a datos (abstracción)
validators/ ← Validaciones de negocio
permissions/ ← Permisos por rol
Tanto Django Admin como FastAPI consumen estos servicios.
Modelo de datos (fuente de verdad)¶
Django Admin y FastAPI comparten los mismos modelos. No hay modelos duplicados.
| Entidad | Ubicación | Notas |
|---|---|---|
| users | Django | Auth, perfil |
| locker_codes | Django | Identificador, prefijo, dígito verificador |
| kyc_records | Django | Documentos, estados |
| purchase_reports | Django | Prealertas |
| tracking_numbers | Django | Múltiples por reporte |
| physical_packages | Django | Paquetes recibidos |
| package_events | Django | Timeline de estados |
| warehouse_locations | Django | Ubicaciones físicas |
| consolidations | Django | Agrupaciones |
| consolidation_packages | Django | Relación N:N |
| shipments | Django | Envíos hacia Cuba |
| quotes | Django | Cotizaciones |
| payments | Django | Pagos |
| payment_attempts | Django | Intentos de pago |
| charges | Django | Cargos generados |
| invoices | Django | Facturas |
| service_requests | Django | Servicios adicionales |
| incidents | Django | Incidencias |
| notifications | Django | Registro de notificaciones |
| audit_logs | Django | Trazabilidad |
| referrals | Django | Red de referidos |
| credit_balances | Django | Crédito por usuario |
| credit_movements | Django | Movimientos de crédito |
| promo_cards | Django | Tarjetas promocionales |
| file_attachments | Django | Metadata de archivos |
| api_tokens | Django | Tokens de API |
| device_tokens | Django | Tokens push por dispositivo |
Frontend — Quasar (Web)¶
Aplicación web SPA con Quasar (Vue.js):
- SPA responsive mobile-first
- Acceso a cámara para fotos de órdenes y paquetes
- Notificaciones push
- Se comunica con FastAPI vía API REST
Apps nativas (Fase 2-3)¶
- iOS: Swift/SwiftUI
- Android: Kotlin/Jetpack Compose
Ambas consumen la API de FastAPI.
Reglas de gobierno del stack¶
| Regla | Descripción |
|---|---|
| Django define modelos | El esquema de base de datos vive en Django. FastAPI no crea tablas propias. |
| Lógica en services/ | Toda la inteligencia de negocio está en core/services/. No en views, no en endpoints. |
| FastAPI es consumer | FastAPI consume servicios, no reimplementa lógica. |
| Redis para sincronización | Locks para procesos críticos (identificador, crédito, pago, consolidación). |
| MinIO para archivos privados | KYC, evidencias y fotos nunca son públicos. URLs firmadas + log de acceso. |
| Migraciones vía Django | Solo Django corre migraciones. FastAPI nunca las toca. |