SaaS de administración de propiedades
Un SaaS multi-tenant que maneja el día a día de empresas de servicios y de administración de propiedad horizontal en Colombia: recaudo, cartera, pagos, solicitudes, trabajo de campo, cotizaciones e informes, con un portal para sus residentes y clientes. Diseñé la arquitectura y lo construí de punta a punta, y corre en producción en Google Cloud.
Camino de una petición en producción
- navegadorapp Next.js
- Next.js en Cloud Runpúblico, renderizado en servidor
- proxy en el servidoragrega un token de identidad firmado por Google
- FastAPI en Cloud Runsolo tráfico interno
- Cloud SQL + Cloud StoragePostgreSQL 16, archivos con URL firmada
Dos planos, cuatro apps
La plataforma se divide por la línea que todo SaaS tiene que trazar: operar el negocio de la plataforma y operar el negocio de cada cliente.
API del plano de control
FastAPI
Registro y login de empresas, planes, suscripciones, organizaciones y su personal. Crear una empresa y su primer administrador es una sola transacción.
API del plano de tenants
FastAPI, ~150 rutas
Todo lo que hace una empresa cliente, en superficies estrictamente separadas: back office, portal de residentes y clientes, y trabajadores de campo.
Portal SaaS
Next.js
Landing, registro, onboarding y gestión de organizaciones, personal y suscripciones para las empresas que compran la plataforma.
App de tenants
Next.js, tres apps en una
Un back office para el personal, un portal de autoservicio para residentes y clientes, y una app mobile-first para trabajadores de campo, cada una con su propia sesión.
Decisiones de arquitectura
- Una base de datos, propiedad clara
- Las dos APIs comparten PostgreSQL, pero cada una es dueña de sus tablas y lleva su propio historial de migraciones, así que evolucionan y se despliegan por separado.
- Sin código compartido en runtime
- Los servicios están desacoplados a propósito: la consistencia viene de contratos escritos, no de una librería compartida que ata cada despliegue.
- Multi-tenancy por filas
- Cada llamada al repositorio va acotada por empresa y organización. Una lectura entre organizaciones devuelve 404, no 403, para que no se puedan enumerar identificadores.
- Planes como feature flags
- Las suscripciones viven a nivel de organización y llevan feature flags; el portal revisa su flag en cada petición.
- Backend por capas, con reglas que se cumplen
- api → domain → data, con módulos de auth, storage y common al lado. Las reglas de imports se verifican automáticamente antes de escribir el código.
- Libro contable solo de inserción
- Los movimientos financieros nunca se modifican en su lugar, y las acciones sensibles registran eventos de auditoría.
- Un solo contrato para errores
- Toda falla devuelve el mismo sobre con código, mensaje y detalles, así que los clientes manejan los errores en un solo lugar.
Identidad y seguridad
- Cuatro tipos de identidad
- Clientes de la plataforma, personal de cada empresa, residentes con enlace seguro y usuarios invitados al portal, cada uno con sus propios tokens y secretos de firma.
- Acceso por roles
- Roles de administración, operaciones, contabilidad, solo lectura y trabajador de campo, verificados en cada ruta; los usuarios del portal tienen una lista de permisos.
- Enlaces seguros bien hechos
- Los enlaces de residentes son tokens opacos que se guardan solo como hashes HMAC-SHA256 y se comparan en tiempo constante.
- APIs fuera de internet
- Los servicios FastAPI solo aceptan tráfico interno de llamadores autenticados. El servidor Next.js los llama con un token de identidad firmado por Google y envía la sesión del usuario en un header aparte.
- Entradas estrictas
- Los modelos de petición rechazan campos desconocidos, la documentación interactiva de la API está apagada fuera de desarrollo local y cada petición lleva un correlation ID.
Corriendo en Google Cloud
- Cloud Run
- Cuatro servicios: las dos APIs escalan a cero y las dos apps Next.js renderizan en el servidor.
- Cloud SQL
- PostgreSQL 16 con backups automáticos, conectado con el conector de Cloud SQL.
- Cloud Storage
- Documentos y logos a través de una interfaz de almacenamiento compatible con S3, servidos con URLs firmadas de corta duración. La misma interfaz corre sobre MinIO en local.
- Entrega
- Un trigger de Cloud Build por repositorio: cada push a main construye una imagen etiquetada con el commit, la guarda en Artifact Registry y la despliega. Las migraciones corren al iniciar el contenedor.
- Mínimo privilegio
- Una cuenta de servicio por servicio: el backend accede a la base de datos, al bucket y a sus secretos; cada frontend solo puede invocar su propia API. Los secretos viven en Secret Manager.
Qué hace la plataforma
- Pagos con revisión y un libro contable auditable
- Cartera con importación y exportación a Excel
- Peticiones, quejas y reclamos (PQRS) con tickets
- Tareas, trabajadores de campo y calendario por horas
- Cotizaciones con ítems, aceptadas o rechazadas desde el portal
- Proyectos, proveedores, gastos e inventario
- Vista 360 del cliente y mapa de clientes y tareas
- Tablero de KPIs, informes financieros y de proveedores
- Documentos adjuntos a cualquier registro
- Copropiedad: unidades, facturación y asambleas
- Reservas y publicaciones para residentes
- Marca blanca por organización
Disciplina de ingeniería
- Pruebas donde importan
- Más de 230 pruebas automatizadas, incluyendo aislamiento entre tenants, restricción por plan y expiración y revocación de tokens, exigidas por la definición de terminado.
- Esquema como código
- 17 migraciones de Alembic entre los dos servicios.
- Decisiones por escrito
- Registros de decisiones de arquitectura, especificaciones numeradas y un roadmap por fases, con cada módulo entregado como su propia fase.
- Asistido por IA, con reglas
- Construido con agentes de programación de IA que trabajan bajo reglas explícitas: un hook bloquea cualquier código que rompa las capas antes de que se escriba.