RexFy
Marketplace B2B de materiales reciclables: conecta generadores de residuos, compradores/transformadores y transportistas.
Arquitectura: monolito modular (ver docs/).
| Carpeta | Qué es |
|---|
apps/web | Frontend Next.js + TypeScript + Tailwind |
apps/api | Backend FastAPI + SQLAlchemy + Alembic |
docs/ | Pack de producto, modelo C4 y blueprint técnico |
Requisitos
- Docker (para PostgreSQL y Redis)
- Node.js 22+
- Python 3.12+ y uv
Arrancar en local
# 1. Base de datos y Redis
docker compose up -d postgres redis
# 2. API (http://localhost:8000, docs en /docs)
cd apps/api
cp .env.example .env
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --reload
# 3. Worker de tareas (emails), en otra terminal desde apps/api
uv run python -m app.worker
# 4. Web (http://localhost:3000), en otra terminal
cd apps/web
cp .env.example .env.local
npm install
npm run dev
Login con Clerk
El ingreso y registro los maneja Clerk. Crea una aplicación en el dashboard de Clerk y copia sus llaves (sección API keys):
- En
apps/web/.env.local: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY y CLERK_SECRET_KEY.
- En
apps/api/.env: REXFY_CLERK_ISSUER (el Frontend API URL, por ejemplo https://tu-app.clerk.accounts.dev) y REXFY_CLERK_SECRET_KEY (la misma secret key).
La API valida el token de sesión de Clerk con sus llaves públicas (JWKS) y, la primera vez que ve a un usuario, lee su correo y nombre de Clerk y lo crea en la base. Las empresas, roles y permisos siguen viviendo en nuestra base.
Datos de demo
La base arranca vacía. Para ver el marketplace con publicaciones de ejemplo (3 empresas, 6 materiales):
cd apps/api
uv run python -m app.cli.seed
Se puede correr varias veces: solo crea lo que falta. Solo funciona con REXFY_ENV=local.
Notificaciones
Mensajes, cotizaciones, órdenes, envíos, disputas y verificaciones crean una notificación en la
app (la campana del encabezado) y un email a los miembros de la empresa. Los emails los manda el
worker; sin REXFY_SMTP_HOST solo se escriben en su log. Para no correr el worker en local,
usa REXFY_TASK_QUEUE=inline.
Admin de RexFy
El panel /admin (verificar empresas, moderar publicaciones, disputas y actividad) es para el
equipo de RexFy. Ingresa una vez con tu cuenta y luego, desde apps/api:
uv run python -m app.cli.admin [email protected] # dar acceso
uv run python -m app.cli.admin [email protected] --revoke # quitarlo
Los transportadores solo ven solicitudes de transporte cuando su empresa está verificada.
La página de inicio muestra el estado de la API, la base de datos y Redis. Si los tres dicen ok, todo está conectado.
Para levantar también la API dentro de Docker: docker compose --profile full up.
Pruebas y lint
cd apps/api && uv run pytest && uv run ruff check .
cd apps/web && npm run lint && npm run typecheck && npm run build
Prueba de punta a punta (Playwright)
apps/web/e2e recorre el marketplace completo en el navegador: tres empresas se registran, RexFy
verifica al transportador, el generador publica, el comprador cotiza y el generador acepta, se
pide y adjudica el transporte, se entrega, y el comprador confirma y califica.
Usa tu instancia de desarrollo de Clerk (las mismas llaves de .env.local y apps/api/.env):
crea usuarios de prueba +clerk_test y los borra al terminar. Con la API corriendo:
cd apps/web
npx playwright install chromium # solo la primera vez
npm run e2e # levanta la web si no está corriendo
En CI corre cuando el repositorio tiene los secretos E2E_CLERK_PUBLISHABLE_KEY,
E2E_CLERK_SECRET_KEY y E2E_CLERK_ISSUER; sin ellos el job se salta.
Los tipos de la web salen del esquema OpenAPI de la API. Si cambias un esquema de la API,
regenéralos (CI falla si quedaron desactualizados):
cd apps/api && uv run python -m app.cli.openapi openapi.json
cd apps/web && npm run api:types
Despliegue en Vercel
Son dos proyectos de Vercel sobre el mismo repositorio:
| Proyecto | Root Directory | Qué corre |
|---|
rexfy-api | apps/api | FastAPI como función de Python (app/main.py) |
rexfy-web | apps/web | Next.js |
Servicios, todos desde el Marketplace / Storage de Vercel y conectados a rexfy-api:
- Neon (Postgres): pone
DATABASE_URL (con pooler) y DATABASE_URL_UNPOOLED. La API usa la
primera sin pool propio (NullPool) y las migraciones la segunda.
- Upstash (Redis): pone
REDIS_URL; lo usa el límite de cambios por minuto.
- Vercel Blob: pone
BLOB_READ_WRITE_TOKEN; ahí quedan las fotos.
Variables de rexfy-api además de esas:
REXFY_ENV=production
REXFY_TASK_QUEUE=inline # no hay worker: los emails salen en la misma petición
REXFY_STORAGE_BACKEND=vercel_blob
REXFY_CORS_ORIGINS=["https://<dominio de la web>"]
REXFY_PUBLIC_WEB_URL=https://<dominio de la web>
REXFY_PUBLIC_API_URL=https://<dominio de la api>
REXFY_CLERK_ISSUER=... # Frontend API URL de Clerk
REXFY_CLERK_SECRET_KEY=...
Variables de rexfy-web: API_URL y NEXT_PUBLIC_API_URL (la URL de la API),
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY y CLERK_SECRET_KEY.
Vercel acepta máximo 4,5 MB por petición; por eso la web comprime las fotos en el navegador
antes de subirlas.
Las migraciones no corren en el deploy. Antes de desplegar un cambio de esquema, desde
apps/api y con la URL directa de Neon:
REXFY_DATABASE_URL_UNPOOLED=postgresql://... uv run alembic upgrade head
