ADR 0001 — Stack y modo de distribución

Estado: Aceptado · Ámbito: arquitectura general

Contexto

FlowFit nace de un prototipo en Flask + SQLite + Jinja2/Bootstrap, pero el cliente real es un solo gimnasio que opera desde una sola computadora (Windows), con un usuario final que nunca ha usado un sistema de administración. Restricciones del negocio:

• Debe funcionar sin internet (la conexión del gimnasio no es confiable).
• Perder el archivo de datos equivale a perder miembros y pagos → respaldo obligatorio.
• No hay necesidad de multi-sucursal ni de un servicio web compartido.

Decisión

• Frontend: React 19 + Vite + TypeScript (Zustand + TanStack Query).
• Backend: Fastify 5 + Prisma 7 sobre SQLite (adaptador better-sqlite3), corriendo como sidecar en 127.0.0.1:3001.
• Distribución: app de escritorio con Tauri 2, que empaqueta el frontend, el sidecar Node y la base SQLite en un instalador .exe (NSIS).
• Datos: una sola base SQLite local (un tenant). Respaldo por snapshots a una carpeta sincronizada por Nextcloud. No se usa Postgres ni Litestream.
• Sin SaaS multi-tenant: descartado explícitamente para este alcance.

Consecuencias

Positivas

• Funciona offline; la latencia es local.
• Despliegue simple: un instalador, sin servidores que administrar.
• El respaldo entra "gratis" copiando un único archivo.
• Stack TypeScript de punta a punta (un solo lenguaje).

Negativas / costos

• Los native addons (better-sqlite3, argon2) obligan a construir el instalador en la plataforma destino (Windows).
• El instalador va sin firmar → aviso de SmartScreen en la primera ejecución.
• Escalar a varios gimnasios requeriría rediseñar tenancy y autenticación (no contemplado hoy).
• Migrar de Flask significó reescribir el prototipo por completo.

Alternativas descartadas

• Postgres / Litestream: innecesario para un solo gimnasio; el daemon de Litestream es frágil en escritorio Windows.
• SaaS web multi-tenant / multi-sucursal: YAGNI para el alcance actual.