WeekBalance Docs

Manual Técnico de WeekBalance

WeekBalance es una plataforma de finanzas personales que combina una aplicación móvil desarrollada con React Native y un backend en Express.js.

Arquitectura del Sistema

Cliente móvil/web

Aplicación Expo (React Native) que consume la API vía HTTPS. Implementa navegación stack, formularios controlados y gráficas interactivas.

Backend

API REST en Express.js (TypeScript) con capa de servicios, repositorios y DTOs. Orquesta operaciones de autenticación, ingresos, egresos, ahorros y balance.

Servicios gestionados

Supabase provee autenticación, base de datos Postgres y almacenamiento seguro de sesiones.

Cron semanal

balance/balance.cron.ts ejecuta cálculos periódicos de balance usando node-cron.

Comunicación

JSON sobre HTTPS; el frontend agrega el token Supabase (Bearer <jwt>) en cada request protegida.

Tecnologías y Herramientas

Frontend

  • Expo 54, React 19, React Navigation
  • React Hook Form, Zustand
  • Expo Linear Gradient, Reanimated
  • Chart Kit y Gifted Charts

Backend

  • Express 5, Supabase JS v2
  • TypeScript 5, ts-node-dev
  • node-cron, JWT, uuid

Infraestructura

  • Configuración central en BackEnd/src/config
  • Variables vía .env

Testing

  • Jest con jest-expo
  • Pruebas unitarias aisladas

Estructura del Proyecto

Frontend (weekbalance/)

  • src/app: pantallas principales, enrutamiento y layout.
  • src/auth: hooks, pantallas y servicios para login/registro.
  • src/balance: componentes, API y hooks para tendencias.
  • src/shared: componentes reutilizables, utilidades.
  • src/core: constantes, configuración HTTP.

Backend (BackEnd/)

  • src/app.ts: instancia Express, middlewares.
  • src/server.ts: arranque HTTP y carga de cron jobs.
  • src/modules: subdirectorios por dominio.
  • src/infrastructure: conexión Postgres vía Supabase.
  • src/middlewares: autenticación y CORS.

API (Comunicación)

Autenticación (/api/auth)

  • POST /login: recibe email, password; responde token.
  • POST /register: crea usuario y cuenta base.
  • GET /profile/:id: lectura de perfil.

Ingresos (/api/incomes)

  • POST /add/: registra ingreso.
  • GET /history/:accountId: historial.
  • PUT /update/: actualiza ingreso.

Gastos (/api/expenses)

Rutas homólogas a ingresos.

Balance (/api/balance)

  • GET /monthly-trend: tendencia mensual.
  • GET /weekly-trend: tendencia semanal.

Base de Datos

Proveedor

Supabase Postgres administrado.

Tabla Columnas
profiles id uuid, full_name, avatar_url, created_at
accounts id uuid, user_id uuid, balance numeric
income_history account_id, amount, category, description

Seguridad

Autenticación

Supabase Auth emite tokens JWT; middleware valida vigencia.

Autorización

Servicios operan sobre accountId ligado al usuario.

Transporte

Requiere HTTPS en despliegues.

Protección de secretos

Variables en .env (excluido del repo).

Instalación y Ejecución

Requisitos

Node.js 20+, npm 10+, Expo CLI, cuentas Supabase.

Frontend

  1. npm install
  2. Copiar .env.example a .env
  3. npm start para Expo Go

Backend

  1. npm install
  2. Definir .env con variables
  3. npm run dev para desarrollo

Flujo del Sistema

  1. Usuario se registra (/api/auth/register).
  2. Backend crea cuenta base y perfil.
  3. Tras login, frontend guarda token y carga perfil.
  4. Usuario registra ingresos/gastos; servicios actualizan balance.
  5. Módulo de ahorros ajusta metas semanales.
  6. Dashboards consultan endpoints de balance.

Pruebas

Frontend

npm test ejecuta jest-expo con @testing-library/react-native.

Backend

Pruebas unitarias aisladas con Jest.

Mantenimiento

  • TypeScript estricto en todo el proyecto.
  • ESLint con normas por defecto de Expo.
  • Scripts npm para builds locales.
  • Variables de entorno centralizadas.

Problemas Comunes

Error de conexión a Supabase

Verificar que las variables SUPABASE_URL y SUPABASE_SERVICE_KEY estén definidas.

Cron job no se ejecuta

Revisar logs del servidor y asegurar que node-cron está instalado.

Error de CORS

Configurar middleware CORS en Express.