GymNova — Documentación técnica
GymNova es una aplicación de administración de gimnasio pensada para un solo
gimnasio, en una sola computadora. No es un servicio web multi-cliente: el
servidor escucha únicamente en 127.0.0.1 y la base de datos vive embebida en
la propia máquina.
:::info Audiencia Esta sección es para el equipo de desarrollo. El Manual de usuario cubre el uso diario sin tecnicismos. :::
Stack real
| Capa | Tecnología |
|---|---|
| Frontend | React 19 · Vite · TypeScript · Zustand · TanStack Query · React Router 7 |
| Backend (sidecar) | Fastify 5 · Prisma 7 (adaptador better-sqlite3) |
| Base de datos | SQLite (archivo local, modo WAL) |
| Autenticación | JWT con jose · hashing de contraseñas con Argon2id |
| Validación | Zod |
| Shell de escritorio | Tauri 2 (Rust) — empaqueta frontend + sidecar Node + SQLite |
| Notificaciones | Backend experimental de Twilio (WhatsApp); producción desactivada |
| Tareas programadas | node-cron (recordatorios diarios) |
| Tooling | Biome (lint + format) · Vitest (tests) |
El stack se verificó leyendo el repositorio (
package.json,prisma/schema.prisma,server/). El proyecto no usa Flask; Flask fue solo el prototipo de origen.
:::warning Integraciones externas
Facturas sólo genera SIMULACION local: no firma, transmite ni recibe acuse del
Ministerio de Hacienda. WhatsApp conserva un backend experimental, con
twilioConnected=false; faltan plantillas aprobadas, sender, consentimiento
verificable, callback HTTPS y E2E real para producción.
:::
Modos de despliegue
GymNova se distribuye como aplicación de escritorio:
- App de escritorio (Tauri / Windows). Un instalador (
.exevía NSIS) empaqueta el frontend compilado, el servidor Fastify como sidecar de Node y la base SQLite. Funciona offline; los respaldos se sincronizan a Nextcloud cuando hay red. Este es el modo de entrega al cliente.
:::caution Modo "SaaS web multi-tenant" — [POR CONFIRMAR]
El brief inicial mencionaba una distribución web multi-tenant. El código no la
implementa y el README.md declara explícitamente "No es un SaaS
multi-tenant"; el roadmap marca multi-sucursal como descartado. Si en el
futuro se decide ofrecer un modo web, este documento debe actualizarse. Por
ahora se documenta solo el modo escritorio.
:::
Cómo está organizado el repositorio
gymnova/
├── src/ # Frontend React, agrupado por dominio
│ ├── app/ # Arranque y armazón
│ ├── shared/ # Lo transversal (ui, lib)
│ └── features/ # Un dominio por carpeta: inicio, miembros, dinero, …
├── server/ # Sidecar Fastify, agrupado por dominio
│ ├── plataforma/ # Arranque e infraestructura: db, migraciones, auditoría…
│ ├── compartido/ # Lo transversal: fechas, guards, precios, secretos…
│ └── <dominio>/ # inicio, acceso, miembros, dinero, facturas, reportes,
│ # whatsapp, gimnasio, respaldo, licencia, recuperacion.
│ # Sus endpoints HTTP son los `rutas-*.ts`
├── prisma/ # schema.prisma, migraciones, seed
├── src-tauri/ # Shell de escritorio (Rust + tauri.conf.json)
├── scripts/ # build-sidecar, fetch-node, make-latest-json, bump-version
└── website/ # Este sitio de documentación (Docusaurus)
Siguientes lecturas
- Arquitectura — diagrama de cómo encajan las piezas.
- Reglas de negocio — fuente única de verdad del dominio.
- Despliegue — levantar el entorno y generar el
.exe. - Referencia de la API — tabla de rutas del sidecar.