Guía para Empleados y Desarrolladores de Renteric

Esta guía es para nuevos empleados, desarrolladores y agentes Paperclip que se incorporan al proyecto Renteric. Explica qué hace el producto, cómo está arquitectada la aplicación, dónde hacer cambios y cómo debe moverse el trabajo a través de issues.

1. Contexto del Producto

Renteric es un SaaS de operaciones de alquileres enfocado primero en Argentina, para propietarios pequeños, administradores boutique e inmobiliarias. Centraliza:

• Propiedades, edificios, unidades, propietarios, inquilinos, garantes y contratos.
• Facturas, cobros, revisión de transferencias, gastos, liquidaciones y reportes.
• Mantenimiento, proveedores, inspecciones, mensajes, notificaciones y documentos.
• Portales de inquilino, propietario, prospecto, publicaciones públicas y panel interno.
• Flujos locales como MercadoPago, ARCA/AFIP, índices BCRA, i18n español/inglés y precios en ARS.

La promesa del producto es gestión automática de alquileres: menos planillas, WhatsApp, recordatorios manuales, registros duplicados y reportes repetidos.

Mapa Visual del Producto

Estas capturas públicas del demo muestran las superficies que todo empleado o desarrollador debería entender antes de cambiar código. Usan datos de demostración y no exponen información privada de clientes.

2. Superficies Principales

La app se organiza por grupos de rutas bajo src/app/[locale]/.

3. Stack Técnico

4. Arquitectura en Una Página

Renteric usa una arquitectura por capas:

1. El navegador solicita una ruta localizada.
2. src/middleware.ts maneja subdominios, locale, redirecciones de auth, CSP, rate limits, cookies y acceso por ruta.
3. Server Components renderizan páginas de lectura y llaman funciones de query.
4. Client Components manejan formularios, tablas, filtros, diálogos y UI optimista.
5. Server Actions manejan mutaciones: validan con Zod, aplican auth/permisos, usan Prisma scoped por organización, auditan, revalidan y retornan ActionResult<T>.
6. API routes se reservan para límites de sistema: webhooks, cron, archivos, integraciones, métricas, búsqueda y callbacks externos.
7. Jobs de fondo corren fuera del request para facturación, recordatorios, sync, reportes, retención y transiciones de ciclo de vida.

Flujo interno por defecto:

Server Component read -> src/server/queries/<domain>.ts -> getScopedDb()
Client form submit -> Server Action -> validator -> getScopedDb() -> ActionResult<T>
External system -> API route -> validated boundary -> service/action/job
Vercel cron -> API route -> BullMQ queue -> worker processor

No agregues endpoints REST para CRUD interno normal. Usá Server Components para lecturas y Server Actions para escrituras.

5. Modelo de Datos y Multi-Tenancy

La cadena central del negocio es:

Organization -> Property -> Unit -> Lease -> Tenant

Modelos adyacentes: propietarios, garantes, facturas, transacciones, gastos, mantenimiento, proveedores, inspecciones, documentos, mensajes, notificaciones, cuentas receptoras, cuentas fiduciarias, solicitudes y estados de propietario.

Todo modelo de datos de clientes tiene organizationId. El aislamiento se aplica con el cliente Prisma scoped de src/server/middleware/with-org-scope.ts.

Reglas que no se pueden romper:

• Usar getScopedDb({ organizationId }) o la DB scoped inyectada por createAction.
• No usar Prisma raw para datos tenant-owned en acciones o queries visibles a usuarios.
• Dejar que el cliente scoped inyecte organizationId y filtros de soft-delete.
• Importar tipos Prisma y Prisma desde @/generated/prisma, no @prisma/client.
• Usar Prisma.Decimal para dinero.
• Tratar como soft-deleted los modelos que siguen esa convención: Property, Unit, Tenant, Vendor, Guarantor, Owner y relacionados.

6. Auth, Roles y Permisos

El estado de auth viaja en sesión/JWT con usuario, organización y rol. Roles y permisos viven en src/config/permissions.ts.

Roles de dashboard:

• ADMIN: acceso amplio a toda la organización.
• MANAGER: acceso operativo, normalmente por propiedades asignadas.
• ACCOUNTANT: finanzas, reportes, cobros y gastos.
• MAINTENANCE: mantenimiento, proveedores, activos, inspecciones y mensajes.

Roles de portal:

• TENANT: solo portal de inquilino.
• OWNER: portal de propietario y visibilidad de lectura.

Reglas de mutación:

• CRUD con permisos debe usar createAction desde src/lib/create-action.ts.
• Usar withPermission, withPermissions, withAuth o withDashboardPermission según patrón local.
• No llamar getAuthSession() directamente como único guard.
• Retornar ActionResult<T> en vez de lanzar errores crudos al cliente.

7. Mapa del Código

No leas completo src/generated/prisma/index.d.ts; es generado y muy grande. Buscá tipos específicos.

8. Cómo Hacer un Cambio

1. Encontrá el dominio por ruta, carpeta de componentes, server action, query o validador.
2. Leé el patrón existente más cercano antes de inventar abstracciones.
3. Agregá o actualizá validación con Zod en src/server/validators.
4. Agregá el camino de lectura en Server Components y queries.
5. Agregá el camino de escritura en Server Actions con auth, permisos, scoped DB y ActionResult<T>.
6. Actualizá UI usando patrones y primitives existentes.
7. Agregá textos en messages/en.json y messages/es.json.
8. Actualizá rutas, permisos, navegación o plan gates si creás superficie nueva.
9. Agregá pruebas enfocadas.
10. Actualizá documentación cuando cambie arquitectura, setup, operación o comportamiento de usuario.

9. Formularios

La mayoría usa React Hook Form y Zod.

• Usar translatedZodResolver(schema, tValidation) para formularios i18n.
• Usar typedZodResolver(schema) para formularios sin traducción.
• El cliente mejora UX, pero el server action siempre vuelve a validar.
• Construir FormData desde datos validados al llamar acciones.
• Mostrar fieldErrors inline cuando existan.

Flujo:

useForm -> resolver -> handleSubmit -> FormData -> server action
server action -> schema.safeParse -> mutation -> ActionResult<T>
success -> toast + router.refresh/revalidate path
failure -> toast and/or form field errors

10. Jobs y Cron

Los jobs viven en src/server/jobs/ y se registran en src/server/jobs/worker.ts. Las rutas cron de Vercel encolan trabajo desde src/app/api/cron/*.

Usalos para facturación, intereses, ajustes, vencimientos, recordatorios, gastos recurrentes, estados de propietario, sync externo, retención y auditoría. Los jobs nuevos deben ser idempotentes, logueados, retry-aware y seguros de reintentar.

11. Integraciones Externas

Las integraciones se envuelven en servicios, no se consumen directamente desde UI.

• MercadoPago y Stripe para pagos/suscripciones.
• Resend, SMTP, Twilio, Meta WhatsApp y Web Push.
• ARCA/AFIP y BCRA para impuestos e índices.
• S3/MinIO y ClamAV para archivos.
• Proveedores de IA para extracción documental.
• Tokko y proveedores de publicaciones.
• Sentry y métricas.

Nunca commitear API keys, tokens, certificados o datos privados. Validar webhooks y entradas externas en el borde.

12. Desarrollo Local

Camino rápido:

make dev-up
make dev

Camino manual:

docker compose up -d
npm install
npx prisma migrate deploy
npm run dev

Comandos útiles:

npm run worker
npm run lint
npm run test
npm run test:changed
npm run test:e2e
npm run build
npm run deploy

Usar npm run deploy:prod solo si el board lo pide explícitamente.

13. Expectativas de Verificación

Elegí verificación según riesgo:

• Solo docs: formatter o sanity check de markdown.
• Validators/actions: tests unitarios enfocados.
• Server behavior compartido: tests afectados más lint o typecheck/build cuando sea práctico.
• Workflow de usuario: Playwright para el path afectado.
• Jobs: tests enfocados y, si se puede, dry-run o worker local.

No declares terminado el trabajo sin verificación real o sin indicar claramente qué no se pudo ejecutar.

14. Workflow Paperclip

Paperclip coordina el trabajo entre board, managers y agentes. El board o un manager crea goals/issues. Los agentes toman issues asignados, trabajan en heartbeats, dejan comentarios o artefactos durables y mueven el issue a un estado claro.

Estados:

• todo: listo pero sin dueño activo.
• in_progress: trabajo activo.
• in_review: espera reviewer, aprobación, interacción o monitor real.
• blocked: necesita acción de un dueño o issue bloqueante.
• done: completo, verificado y sin seguimiento.
• cancelled: abandonado intencionalmente.

Reglas:

• Trabajar solo en issues asignados salvo mención explícita.
• Hacer checkout salvo que el harness ya lo haya hecho.
• No cambiar de issue dentro del heartbeat.
• Usar comentarios con estado, links y verificación.
• Usar child issues para trabajo largo, paralelo o de otro agente.
• Usar blockers de primera clase.
• Marcar done solo cuando el pedido esté completo.

15. Cómo Crear Buenos Issues Paperclip

Creá un issue cuando el trabajo necesite dueño, review o auditoría.

Incluí:

• Título con resultado visible.
• Motivo de negocio o contexto fuente.
• Alcance incluido y fuera de alcance.
• Archivos, rutas o docs relevantes.
• Criterios de aceptación.
• Verificación requerida.
• Dependencias o blockers.
• Perfil sugerido de dueño cuando se conozca.

Plantilla:

## Objetivo

Agregar export CSV para liquidaciones de propietarios.

## Alcance

- Acción de export en el dominio de liquidaciones.
- Columnas: propietario, propiedad, período, renta bruta, gastos, comisión y neto.
- Botón en la página de detalle.
- Reutilizar patrones de export existentes.

## Fuera de Alcance

- Nuevos gráficos.
- Cambios al cálculo de liquidaciones.

## Criterios de Aceptación

- Export solo para usuarios con permisos financieros.
- Filas scoped por organización.
- Estados vacíos y errores traducidos.
- Tests enfocados cubren permisos y columnas.

## Verificación

- Tests unitarios del export.
- Lint en archivos cambiados.

Al mencionar otro issue, usá link interno como [REN-123](/REN/issues/REN-123).

16. Checklist de Review

• Multi-tenancy: sin Prisma raw para datos tenant-owned.
• Auth: toda mutación protegida.
• Type safety: sin any nuevo; Prisma desde @/generated/prisma.
• Validación: entradas externas parseadas con Zod.
• Dinero: decimales, no floats.
• Performance: sin queries sin límite ni N+1.
• Seguridad: sin secretos, stack traces ni uploads sin validar.
• Auditoría: mutaciones importantes registran actividad.
• i18n: textos visibles en inglés y español.
• Tests: pruebas enfocadas o verificación documentada.
• Deploy: después de commit limpio, correr npm run deploy salvo producción.

17. Cuando Hay Dudas

El código existente es la primera autoridad:

• Buscá un dominio similar.
• Leé validador, query, action, componente y test juntos.
• Preferí cambios pequeños que encajen en el patrón local.
• Escalá decisiones estratégicas, presupuesto o cambios irreversibles al board.