Monorepo (Frontend + Backend + Contrato API)

Este repositorio contiene:

• apps/frontend: app web en React + Vite + TanStack Router/Query.
• apps/backend: API en Bun + Hono + Prisma + Supabase Auth.
• packages/api-contract: contratos compartidos (schemas/types/rutas) entre frontend y backend.

Objetivo de este README

Dejarte productivo/a en pocos minutos para que puedas:

1. Levantar frontend y backend en local.
2. Configurar variables de entorno.
3. Ejecutar migraciones de base de datos.
4. Entender la estructura y el flujo de trabajo del proyecto.

Stack técnico

• Runtime/package manager: bun
• Frontend: React 19, Vite, TanStack Router, TanStack Query
• Backend: Bun, Hono, Prisma, PostgreSQL
• Auth: Supabase Auth (token Bearer validado en backend)
• Validación de contratos: zod en @repo/api-contract

Prerrequisitos

• bun instalado (versión reciente).
• PostgreSQL corriendo localmente (o accesible remotamente).
• Proyecto de Supabase para autenticación (URL + anon key).

Setup rápido

1. Instalar dependencias desde la raíz:

bun install

2. Configurar variables de entorno del backend:

cp apps/backend/.env.example apps/backend/.env

3. Configurar variables de entorno del frontend:

cp apps/frontend/.env.example apps/frontend/.env

4. Revisar/editar valores en ambos .env según tu entorno.

Variables de entorno

Backend (apps/backend/.env)

Variables esperadas:

• SUPABASE_URL
• SUPABASE_ANON_KEY
• CORS_ORIGIN (por defecto local frontend)
• LOG_LEVEL
• DATABASE_URL (PostgreSQL)

Notas:

• El backend también acepta VITE_SUPABASE_URL y VITE_SUPABASE_ANON_KEY como fallback.
• Si falta DATABASE_URL, Prisma no puede inicializarse.

Frontend (apps/frontend/.env)

Variables esperadas:

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY
• VITE_API_BASE_URL (por defecto: http://localhost:3000)

Base de datos (Prisma)

Antes de arrancar backend por primera vez, corré migraciones:

bun --filter backend prisma:migrate

Si cambiás el schema, regenerá cliente:

bun --filter backend prisma:generate

Ejecutar en desarrollo

Terminal 1 (backend):

bun run dev:backend

Terminal 2 (frontend):

bun run dev:frontend

Puertos por defecto:

• Frontend: http://localhost:5173
• Backend: http://localhost:3000

Scripts útiles

Desde la raíz:

• bun run dev:frontend
• bun run dev:backend
• bun run build:frontend
• bun run lint:frontend

Desde apps/backend:

• bun run dev
• bun run start
• bun run prisma:migrate
• bun run prisma:generate

Estructura del repo

.
├─ apps/
│  ├─ frontend/          # UI y navegación
│  └─ backend/           # API, auth middleware, acceso a DB
└─ packages/
   └─ api-contract/      # Schemas/tipos/rutas compartidos

Flujo de autenticación (resumen)

1. Frontend autentica con Supabase.
2. Frontend guarda el access token y lo envía como Authorization: Bearer ... al backend.
3. Backend valida token con Supabase (requireAuth middleware).
4. Si el token es válido, habilita rutas protegidas (/api/user/*, /api/tenants/*).

Endpoints principales

• GET /api/user/profile
• POST /api/tenants
• GET /api/tenants/:id
• PATCH /api/tenants/:id

Convenciones recomendadas para el equipo

• Mantener contratos de API en packages/api-contract (evitar duplicar tipos).
• Si agregás/cambiás endpoint:
  1. Actualizá schema/tipos en api-contract.
  2. Implementá handler/ruta en backend.
  3. Consumí el contrato desde frontend.
• Validar payloads con Zod tanto en contrato como en rutas.
• Mantener PRs chicos y enfocados.

Troubleshooting rápido

• Error de CORS:
  • Revisar CORS_ORIGIN en backend y que incluya http://localhost:5173.
• 403 Missing bearer token:
  • Verificar login en frontend y envío del header Authorization.
• Error de Supabase env vars:
  • Confirmar SUPABASE_URL/SUPABASE_ANON_KEY (backend) y VITE_* (frontend).
• Error de Prisma/DB:
  • Confirmar DATABASE_URL, conectividad a PostgreSQL y migraciones aplicadas.

Primer día sugerido para onboarding

1. Levantar backend y frontend en local.
2. Crear usuario o iniciar sesión desde la pantalla de onboard.
3. Crear un tenant de prueba.
4. Probar lectura/edición de tenant.
5. Revisar packages/api-contract para entender cómo se comparten tipos y rutas.

---

Si te trabás en el setup, empezá verificando .env, estado de PostgreSQL y que ambos procesos (dev:backend y dev:frontend) estén corriendo.