Arquitectura técnica
Documento complementario a arquitectura-general.md.
Define el stack tecnológico, el diagrama de componentes UML y el diagrama de despliegue del sistema, con versiones exactas verificadas en documentación oficial.
1. Stack tecnológico del proyecto
1.1 Backend
1.2 Frontend
1.3 Datos e infraestructura
| Componente |
Tecnología |
Versión |
| Base de datos |
PostgreSQL |
16.x |
| Cache / broker |
Redis |
7.x |
| Object Storage |
MinIO |
RELEASE.2024-10 (S3 compatible) |
| Búsqueda |
OpenSearch |
2.x |
| Mensajería |
RabbitMQ (opcional) |
3.13.x |
| Contenedores |
Docker + Docker Compose |
24+ / 2.27+ |
| Orquestación |
Kubernetes (opcional) |
1.30+ |
| Reverse proxy |
Nginx |
1.26.x |
| TLS |
Let's Encrypt / Cert institucional |
— |
| Logs |
Loki + Promtail (o ELK) |
última |
| Métricas |
Prometheus + Grafana |
última |
| CI/CD |
GitHub Actions |
— |
1.4 Documentación
| Componente |
Tecnología |
Versión |
| Generador |
MkDocs |
1.6.x |
| Tema |
mkdocs-material |
9.5.x |
| Extensiones |
pymdown-extensions |
10.x |
2. Diagrama de componentes UML
flowchart TB
subgraph Presentacion [Frontend - Vue 3.5 + Vite 7]
UI[App SPA Vue Router]
PWA[Service Worker / PWA]
PiniaStore[Pinia Store]
Componentes[shadcn-vue + Tailwind]
end
subgraph CapaAplicacion [Backend - Django 5.2 + Django Ninja]
APIGateway[NinjaAPI - OpenAPI auto]
Auth[Autenticación: django-allauth + RegID]
Permisos[django-rules RBAC]
Negocio[Servicios de Dominio]
Tareas[Celery 5.4 + Redis 7]
Auditoria[django-auditlog]
Docs[Gestor Documental S3]
end
subgraph Dominio [Aplicaciones Django]
ModProgramas[programas]
ModMatricula[matricula]
ModExpediente[expediente]
ModAcademico[academico]
ModEvaluacion[evaluacion_final]
ModCertifica[certificacion]
end
subgraph Datos [Persistencia]
DB[(PostgreSQL 16)]
Cache[(Redis 7)]
RepoDocs[(MinIO S3)]
end
subgraph Integraciones [Adaptadores]
RegIDComp[Adaptador RegID - OAuth/OIDC]
MoodleComp[Adaptador Moodle - REST]
SGDComp[Adaptador SGD]
ContableComp[Adaptador Contable]
MESComp[Adaptador MES/COPEP]
end
UI --> APIGateway
PWA --> UI
PiniaStore --> UI
Componentes --> UI
APIGateway --> Auth
APIGateway --> Permisos
APIGateway --> Negocio
APIGateway --> Auditoria
Negocio --> Tareas
Negocio --> Docs
Negocio --> ModProgramas
Negocio --> ModMatricula
Negocio --> ModExpediente
Negocio --> ModAcademico
Negocio --> ModEvaluacion
Negocio --> ModCertifica
ModMatricula --> Docs
Docs --> RepoDocs
ModExpediente --> DB
ModProgramas --> DB
ModAcademico --> DB
ModEvaluacion --> DB
ModCertifica --> DB
Tareas --> Cache
Tareas --> DB
Auditoria --> DB
Auth --> RegIDComp
ModAcademico --> MoodleComp
Docs --> SGDComp
ModMatricula --> ContableComp
ModCertifica --> MESComp
3. Diagrama de despliegue
flowchart TB
subgraph Cliente
Navegador[Navegador Web - Vue 3.5 build Vite 7]
Movil[Dispositivo Móvil / PWA]
end
subgraph DMZ
Nginx[Nginx Reverse Proxy + TLS]
WAF[ModSecurity WAF]
end
subgraph ClusterAplicacion [Docker Swarm / K8s]
Django1[Django 5.2 + Gunicorn 1]
Django2[Django 5.2 + Gunicorn 2]
Django3[Django 5.2 + Gunicorn 3]
Worker1[Celery Worker 1]
Worker2[Celery Worker 2]
Beat[Celery Beat - cron]
end
subgraph ClusterDatos
PGPrimario[(PostgreSQL 16 Primario)]
PGReplica[(PostgreSQL 16 Réplica)]
RedisInst[(Redis 7 Cluster)]
MinIO[MinIO S3]
end
subgraph Observabilidad
Prom[Prometheus]
Graf[Grafana]
Loki[Loki + Promtail]
end
subgraph Externos
RegIDExt[RegID - OIDC]
MoodleExt[Moodle]
SGDExt[Gestión Documental]
MESExt[MES / COPEP]
end
Navegador --> Nginx
Movil --> Nginx
Nginx --> WAF
WAF --> Django1
WAF --> Django2
WAF --> Django3
Django1 --> PGPrimario
Django2 --> PGPrimario
Django3 --> PGPrimario
PGPrimario -. replicación streaming .-> PGReplica
Django1 --> RedisInst
Django2 --> RedisInst
Django3 --> RedisInst
Beat --> Worker1
Beat --> Worker2
Django1 --> Worker1
Django2 --> Worker2
Worker1 --> PGPrimario
Worker2 --> RedisInst
Django1 --> MinIO
Worker1 --> MinIO
Django1 -. HTTPS/OIDC .-> RegIDExt
Django1 -. HTTPS/REST .-> MoodleExt
Django1 -. HTTPS/SOAP .-> SGDExt
Django1 -. HTTPS/XML .-> MESExt
Prom --> Django1
Prom --> Django2
Prom --> Django3
Loki --> Django1
4. Estructura de carpetas propuesta
posgrado-backend/
├── manage.py
├── pyproject.toml
├── requirements/
│ ├── base.txt
│ ├── dev.txt
│ └── prod.txt
├── .env.example
├── conftest.py
├── posgrado/ # Proyecto Django
│ ├── settings/
│ │ ├── base.py
│ │ ├── dev.py
│ │ └── prod.py
│ ├── urls.py
│ ├── asgi.py
│ └── wsgi.py
├── apps/
│ ├── accounts/ # Auth, usuarios, roles
│ ├── programas/ # M-04 Programas
│ ├── ediciones/ # M-05 Ediciones
│ ├── convocatorias/ # M-06 Convocatorias
│ ├── matricula/ # M-07 Solicitudes + M-10 Matrícula
│ ├── documentos/ # M-08 Gestión documental
│ ├── expediente/ # M-09 Expediente
│ ├── academico/ # M-11 Ejecución + M-12 Seguimiento
│ ├── evaluacion_final/ # M-13 Evaluación final
│ ├── certificacion/ # M-14 Certificación y titulación
│ ├── reportes/ # M-15 Reportes
│ └── integraciones/ # M-16 Adaptadores externos
├── api/ # Routers Django Ninja
│ ├── router.py
│ └── schemas/
├── core/ # Utilidades compartidas
│ ├── permissions.py # django-rules
│ ├── audit.py
│ └── exceptions.py
└── tests/
posgrado-frontend/
├── package.json
├── vite.config.ts
├── tsconfig.json
├── index.html
├── .env.example
├── src/
│ ├── main.ts
│ ├── App.vue
│ ├── router/ # Vue Router 4
│ ├── stores/ # Pinia 2
│ │ ├── auth.ts
│ │ ├── matricula.ts
│ │ └── programa.ts
│ ├── api/ # Cliente HTTP + tipos
│ │ ├── client.ts
│ │ └── modules/
│ ├── components/ # shadcn-vue generados
│ │ └── ui/ # button, input, dialog, ...
│ ├── composables/ # @vueuse/core
│ ├── views/ # Páginas
│ ├── layouts/
│ ├── locales/ # vue-i18n
│ └── assets/
├── public/
└── tests/
├── unit/ # Vitest
└── e2e/ # Playwright
5. Decisiones de arquitectura (ADR resumen)
| Decisión |
Alternativas |
Elección |
Motivo |
| Framework backend |
FastAPI / NestJS / Django |
Django 5.2 LTS + Django Ninja |
ORM maduro, admin, seguridad, ecosystem institucional, soporte LTS hasta abril 2028. |
| Framework API |
DRF / Ninja |
Django Ninja 1.4 |
Type hints, OpenAPI automático, rendimiento, menos boilerplate. |
| Frontend |
React / Vue |
Vue 3.5 + Vite 7 |
Curva de aprendizaje, ecosistema shadcn-vue/Tailwind, bundle ligero, PWA sencilla. |
| Build tool |
Webpack / Vite |
Vite 7 |
HMR instantáneo, builds con Rolldown, ESM nativo. |
| Estado global |
Vuex / Pinia |
Pinia 2.2 |
API moderna, TypeScript-first, recomendado oficialmente. |
| UI Components |
Vuetify / PrimeVue / shadcn-vue |
shadcn-vue + Tailwind |
Copia el código a tu repo, accesibilidad, customizable, basado en Reka UI. |
| Base de datos |
MySQL / PostgreSQL |
PostgreSQL 16 |
JSON nativo, replicación, extensiones, soporte GIS futuro. |
| Cache / broker |
Redis 6 / Redis 7 |
Redis 7 |
Streams, mejor rendimiento, soporte actual. |
| Tareas async |
RQ / Celery |
Celery 5.4 |
Madurez, dashboards Flower, integración Django. |
| Auth |
JWT propio / django-allauth |
django-allauth + RegID OIDC |
SSO institucional, MFA, recovery flows. |
| Permisos |
Django perms / django-rules |
django-rules |
Permisos por objeto sin tablas extra, alto rendimiento. |
| Despliegue |
On-premise / Nube |
On-premise institucional |
Soberanía del dato, normativa cubana. |
| Documentos |
DMS / MinIO |
MinIO S3 en MVP → DMS vía adaptador |
Compatibilidad S3, fácil migración futura. |
6. Atributos de calidad priorizados
| Atributo |
Prioridad |
Estrategia técnica |
| Seguridad |
Muy alta |
HTTPS, HSTS, CSP, RBAC con django-rules, cifrado en reposo (LUKS/KMS), django-axes para fuerza bruta, auditoría inmutable. |
| Trazabilidad |
Muy alta |
django-auditlog + tabla append-only + hash chain + exportación firmada. |
| Disponibilidad |
Alta |
PostgreSQL con réplica + failover, 3 instancias Django detrás de Nginx, Redis Sentinel, backups 3-2-1. |
| Escalabilidad |
Media |
Stateless (sesiones en Redis), Celery workers horizontales, CDN para assets Vite, code splitting por ruta. |
| Usabilidad |
Alta |
shadcn-vue accesible (ARIA), diseño responsivo, validación inline, i18n con vue-i18n. |
| Mantenibilidad |
Alta |
Capas separadas (apps Django por módulo), pruebas >80% cobertura, CI/CD con GitHub Actions, linters ESLint+Prettier+Black+Ruff. |
| Interoperabilidad |
Alta |
OpenAPI 3.1 autogenerado (Django Ninja), adaptadores con circuit breaker, formatos PDF/XLSX/XML oficiales. |
| Performance |
Alta |
select_related/prefetch_related, índices en PostgreSQL, paginación cursor, cache por consulta, bundle Vite con code splitting. |
| Observabilidad |
Alta |
Prometheus + Grafana + Loki + Sentry (errores) + OpenTelemetry tracing. |
7. Entornos y configuración
| Entorno |
Backend |
Frontend |
DB |
Redis |
| Local dev |
Django runserver |
Vite dev server (HMR) |
PostgreSQL 16 (Docker) |
Redis 7 (Docker) |
| CI |
pytest + ruff + mypy |
vitest + eslint + tsc |
SQLite in-memory |
fakeredis |
| Staging |
Gunicorn + Nginx |
build Vite servido por Nginx |
PostgreSQL 16 |
Redis 7 |
| Producción |
Gunicorn + Nginx + K8s |
build Vite + CDN |
PostgreSQL 16 cluster |
Redis 7 cluster |
8. Variables de entorno clave
# Backend
DJANGO_SETTINGS_MODULE=posgrado.settings.prod
DJANGO_SECRET_KEY=<generar>
DJANGO_ALLOWED_HOSTS=posgrado.uc.edu.cu
DATABASE_URL=postgres://user:pass@db:5432/posgrado
REDIS_URL=redis://redis:6379/0
CELERY_BROKER_URL=redis://redis:6379/1
CELERY_RESULT_BACKEND=redis://redis:6379/2
OIDC_RP_CLIENT_ID=<regid>
OIDC_RP_CLIENT_SECRET=<regid>
S3_ENDPOINT_URL=https://minio.uc.cu
S3_ACCESS_KEY=<minio>
S3_SECRET_KEY=<minio>
SENTRY_DSN=<sentry>
# Frontend
VITE_API_BASE_URL=https://api.posgrado.uc.cu
VITE_OIDC_ISSUER=https://regid.uc.cu
VITE_OIDC_CLIENT_ID=posgrado-frontend
9. Ciclo de vida de actualización
- Django 5.2 LTS: soporte oficial hasta abril 2028 (3 años LTS + 1 año extendido).
- Vue 3.5: línea estable; se actualizará a Vue 3.6 cuando sea GA.
- Vite 7: rama estable; se evaluará migración a Vite 8 al estabilizarse.
- Node.js 20 LTS para el toolchain de frontend.
- Python 3.11 LTS para backend (compatible con 3.12 y 3.13).