185 lines
4.5 KiB
Markdown
185 lines
4.5 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
bun install
|
|
```
|
|
|
|
2. Configurar variables de entorno del backend:
|
|
|
|
```sh
|
|
cp apps/backend/.env.example apps/backend/.env
|
|
```
|
|
|
|
3. Configurar variables de entorno del frontend:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
bun --filter backend prisma:migrate
|
|
```
|
|
|
|
Si cambiás el schema, regenerá cliente:
|
|
|
|
```sh
|
|
bun --filter backend prisma:generate
|
|
```
|
|
|
|
## Ejecutar en desarrollo
|
|
|
|
Terminal 1 (backend):
|
|
|
|
```sh
|
|
bun run dev:backend
|
|
```
|
|
|
|
Terminal 2 (frontend):
|
|
|
|
```sh
|
|
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
|
|
|
|
```txt
|
|
.
|
|
├─ 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.
|