finances-api

Migración de finances-backend (Express4+MySQL+JWT) a Hono+TypeScript+Drizzle+PostgreSQL+Better-Auth. Ver CLAUDE.md, .claude/ARCHITECTURE.md y docs/adr/001-initial-architecture.md.

Arquitectura

Hexagonal — domain/ y application/ cero dep de infrastructure/. Mismo stack y misma base de datos que ladder-api (ver .claude/STACK.md). Auth: Better-Auth con cookies httpOnly de sesión (30 días), en vez del JWT Bearer del finances-backend legacy. Contrato de API se mantiene idéntico en paths y shape {success, data, error}.

Desarrollo

npm install
cp .env.example .env.local   # completar valores reales
npm run db:migrate           # drizzle-kit push, aplica el schema directo (solo dev)
npm run dev

npm run db:migrate no genera carpeta drizzle/ — el flujo de desarrollo usa drizzle-kit push (sin journal de migraciones). Para producción, generar migraciones versionadas con npm run db:generate y aplicarlas con npm run db:deploy (drizzle-kit migrate). Nunca correr db:migrate (push) contra producción.

Env vars

Propias de este mundo (además de DATABASE_URL, BETTER_AUTH_SECRET):

OPENAI_API_KEY        # gpt-4o vision, escaneo de recibos
PLAID_CLIENT_ID
PLAID_SECRET          # sync bancario, cron node-cron cada 24h

Tests

npm run test         # vitest run
npm run test:watch   # vitest, modo watch

Tests unitarios en test/application/*.spec.ts (services) y test/infrastructure/*.spec.ts (repositories + http helpers). El cliente Drizzle (db) se mockea vía test/helpers/drizzle-mock.ts — no requieren base de datos real.

Branches y CI

master (producción, deploy automático vía Coolify) y develop (integración). CI (.github/workflows/ci.yml) corre en push/PR a ambas: typecheck → test → build → Semgrep. Deploy a Coolify solo dispara en push a master.

Conectar a la base de datos de producción (Coolify)

El host de DATABASE_URL en .env (producción) es un nombre interno de la red Docker de Coolify — no resuelve desde fuera del VPS. Para conectarte desde local (migraciones, seed, db:studio, etc.), abrí un túnel SSH primero:

ssh -L 5433:127.0.0.1:5433 root@100.105.232.32 -N

Con el túnel abierto, los scripts db:* usan DATABASE_URL de .env.local (localhost:5433), que queda apuntando a producción a través del túnel.

Arquitectura

Ver diagrama interactivo