Stack Tecnológico de UnoSportClub

Este documento describe el stack tecnológico completo de UnoSportClub, basado en tecnologías open source modernas y probadas.

1. Frontend

1.1 Framework Principal

  • Angular 21.x: Framework principal para aplicaciones web

  • TypeScript: Superset de JavaScript con tipado estático

  • HTML5/CSS3: Estándares web modernos

  • Angular Signals: Gestión de estado reactivo

  • Standalone Components: Componentes independientes sin NgModules

1.2 Estilos y UI

  • Tailwind CSS: Framework CSS utility-first para diseño responsive

  • SCSS/SASS: Preprocesador CSS (opcional)

  • Responsive Design: Mobile-first approach

  • Progressive Web Apps (PWA): Capacidades nativas en web

  • Service Workers: Funcionalidad offline y caché

1.3 Herramientas Frontend

  • Angular CLI: Herramientas de línea de comandos

  • RxJS: Programación reactiva y observables

  • Angular Material: Componentes de UI (opcional)

  • FullCalendar: Componente de calendario para reservas

  • NgOptimizedImage: Optimización automática de imágenes

1.4 Aplicaciones Frontend

Cinco SPAs Angular (puertos locales con npm run dev:serve):

| App | Ruta código | Puerto | |-----|-------------|--------| | Cliente | src/ | 6100 | | Panel | projects/panel/ | 6101 | | Trainer | projects/trainer/ | 6102 | | Sudo | projects/sudo/ | 6103 | | Accounting | projects/accounting/ | 6104 |

Librería compartida: projects/common/ (@cortex-ia-com-co/common).

2. Backend

2.1 Runtime y Framework

  • Node.js: Runtime de JavaScript en el servidor

  • Express.js 5.x: Framework web minimalista y flexible

  • HTTP Server: Servidor HTTP nativo de Node.js

2.2 APIs y Comunicación

  • RESTful APIs: Arquitectura REST con endpoints organizados por namespace

  • JSON: Formato de intercambio de datos

  • Middleware: Procesamiento de peticiones (autenticación, autorización, validación)

  • Swagger/OpenAPI: Documentación interactiva de la API

2.3 Estructura de Rutas

El backend está estructurado en namespaces:

  • functions/routes/admin/ - Operaciones administrativas (operator, admin, sudo)

  • functions/routes/account/ - Operaciones de cuenta de usuario (user)

  • functions/routes/trainer/ - Operaciones de entrenador (trainer)

  • functions/routes/sudo/ - Operaciones de super usuario (sudo)

  • functions/routes/accounting/ — Contabilidad NIIF

  • functions/routes/public/ — Endpoints públicos

  • functions/routes/bot/ — Bot e integraciones

2.4 Sistema Realtime

  • Socket.io: Servidor WebSocket para comunicación en tiempo real

  • Sistema Relay: Gateway inmutable para notificaciones y mensajería

  • Redis: Caché de sesiones WebSocket y adapter para escalado horizontal

  • Apache Kafka: Cola de mensajes y streaming de eventos

3. Base de Datos y Almacenamiento

3.1 Base de Datos Principal

  • PostgreSQL: Base principal + DB_NAME_ACCOUNTING (contabilidad)

  • Node.js >= 24 (ver package.json engines)

  • Zona horaria: America/Bogota

3.2 Almacenamiento y Caché

  • Redis:

  • Caché de sesiones WebSocket

  • Adapter para Socket.io (escalado horizontal)

  • Sistema pub/sub para notificaciones

  • Configurado mediante variable de entorno REDIS_URL

3.3 Mensajería

  • Apache Kafka:

  • Cola de mensajes para procesamiento asíncrono

  • Streaming de eventos del sistema Relay

  • Persistencia de mensajes para garantizar entrega

  • Procesamiento de eventos en tiempo real

4. Autenticación y Autorización

4.1 Autenticación

  • OAuth2 local authentication: Autenticación de usuarios

  • Email/password

  • OAuth (Google, Facebook, etc.)

  • Tokens JWT

  • Custom Claims para roles y permisos

4.2 Autorización

  • Role-Based Access Control (RBAC):

  • operator: Operador/Recepcionista

  • admin: Administrador

  • sudo: Super Usuario

  • trainer: Entrenador

  • accounting: Contabilidad NIIF

  • Middleware de Autorización:

  • JWT OAuth2 middleware: Verificación de tokens JWT

  • requireAdminAccess: Control de acceso para admin/operator/sudo

  • requireSudoAccess: Control de acceso exclusivo para sudo

  • requireAccountAccess: Control de acceso para usuarios regulares

  • requireTrainerAccess: Control de acceso para entrenadores

5. Infraestructura y Despliegue

5.1 Imagen Docker unificada (v0.4)

  • Dockerfile en raíz del monorepo: nginx (:80) + Node API (:5000 interno)

  • Publicación en GHCR; tags staging, vX.Y.Z

  • Antora incluido en build (docs/npm run build:local)

  • Virtual hosts por UNOSPORT_HOST_* (app, panel, trainer, sudo, accounting, docs)

5.2 Reverse Proxy (opcional)

  • Caddy u otro proxy TLS delante del contenedor

  • Terminación SSL, health checks, rate limiting

6. DevOps y Herramientas

6.1 Control de Versiones

  • Git: Sistema de control de versiones

  • GitHub: Repositorio y colaboración

  • Monorepo único: docs/, functions/, projects/* en el mismo repositorio (sin submódulos)

6.2 CI/CD

Marco de gobernanza: Entornos, versiones y ciclos. Detalle del pipeline: CI/CD y DevOps.

  • GitHub Actions: .github/workflows/ci.yml (monorepo)

  • Testing automatizado: npm test en PR y develop

  • GHCR: imagen unificada staging / vX.Y.Z

  • Docs: docs/.github/workflows/deploy.yml → GitHub Pages

6.3 Herramientas de Desarrollo

  • npm: Gestor de paquetes Node.js

  • Angular CLI: Herramientas de desarrollo Angular

  • Jest: Tests backend en functions/tests

  • ESLint: Linter para JavaScript/TypeScript

  • Prettier: Formateador de código

  • Husky: Git hooks

  • Lint-staged: Linting pre-commit

6.4 Base de Datos

  • psql: Cliente PostgreSQL CLI

  • pgAdmin / DBeaver: Clientes gráficos de PostgreSQL

  • Migraciones: Sistema de migraciones SQL en functions/db/migrations/

  • Seeders: Datos iniciales en functions/db/seeders/

7. Estructura del Stack

┌─────────────────────────────────────┐
│     Frontend (Angular 21.x)         │
│  TypeScript + Tailwind CSS + PWA    │
│  5 aplicaciones + common            │
└──────────────┬──────────────────────┘
               │
               │ HTTP/REST + WebSocket
               │
┌──────────────▼──────────────────────┐
│   Docker (nginx + Node) / Caddy     │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│   Express.js (functions/server.js)    │
│   OAuth2 local + Relay (Socket.io)  │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│   PostgreSQL (+ DB_NAME_ACCOUNTING)   │
│   Redis / Kafka (Relay, opcional)   │
└─────────────────────────────────────┘

8. Versiones Específicas

8.1 Frontend

  • Angular: ^21.0.2

  • TypeScript: ^5.7.3

  • RxJS: ~7.8.0

  • Tailwind CSS: Última versión estable

  • FullCalendar: ^6.1.19

8.2 Backend

  • Node.js: >=24 (engines en package.json)

  • Express: ^5.1.0

  • PostgreSQL Driver: ^8.16.3

  • Socket.io: ^4.8.1

  • jsonwebtoken / jwks: validación OAuth2 local

8.3 Infraestructura

  • Docker + GHCR

  • PostgreSQL: 14+

  • Redis / Kafka: opcionales (Relay)

  • Caddy: opcional en borde TLS

8.4 Consultar Versiones Exactas

Las versiones específicas están documentadas en:

  • package.json - Dependencias del proyecto principal

  • functions/package.json - Dependencias del backend

  • package-lock.json - Versiones exactas bloqueadas

9. Actualización del Stack

9.1 Política de Actualizaciones

  • Actualizaciones de seguridad prioritarias

  • Actualizaciones menores regulares

  • Actualizaciones mayores con evaluación exhaustiva

  • Testing completo antes de actualizar en producción

9.2 Compatibilidad

  • Mantener compatibilidad con versiones anteriores cuando sea posible

  • Documentar breaking changes

  • Proporcionar guías de migración

  • Versionado semántico para APIs

10. Referencias