ES

Property Management SaaS

Role
Architecture & engineering
Type
Production
Focus
Multi-tenant SaaS on GCP

A multi-tenant SaaS that runs the day-to-day of service and property-administration companies in Colombia: collections, receivables, payments, requests, field work, quotes and reports, with a portal for their residents and clients. I designed the architecture and built it end to end, and it runs in production on Google Cloud.

Request path in production

  1. browserNext.js app
  2. Next.js on Cloud Runpublic, server-rendered
  3. server-side proxyadds a Google-signed identity token
  4. FastAPI on Cloud Runinternal ingress only
  5. Cloud SQL + Cloud StoragePostgreSQL 16, presigned files

Two planes, four apps

The platform is split along the line every SaaS has to draw: running the business of the platform, and running the business of each customer.

Control-plane API

FastAPI

Company sign-up and login, plans, subscriptions, organizations and their staff. Creating a company and its first admin is one transaction.

Tenant-plane API

FastAPI, ~150 routes

Everything a customer company does, served on strictly separated surfaces: back office, resident / client portal and field workers.

SaaS portal

Next.js

Landing, sign-up, onboarding, organizations, staff and subscription management for the companies that buy the platform.

Tenant app

Next.js, three apps in one

A back office for staff, a self-service portal for residents and clients, and a mobile-first app for field workers, each with its own session.

Architecture decisions

One database, clear ownership
Both APIs share PostgreSQL but own different tables and keep separate migration histories, so each can evolve and deploy on its own.
No shared runtime code
The services stay decoupled on purpose: consistency comes from written contracts, not from a shared library that couples every deploy.
Row-level multi-tenancy
Every repository call is scoped by company and organization. A read across organizations returns 404, not 403, so identifiers cannot be enumerated.
Plans as feature flags
Subscriptions live at organization level and carry feature flags; the portal checks its flag on every request.
Layered backend, enforced
api → domain → data, with auth, storage and common modules beside them. Import rules are checked automatically before code is written.
Append-only ledger
Financial movements are never updated in place, and sensitive actions write audit events.
One contract for errors
Every failure returns the same envelope with a code, a message and details, so clients handle errors in one place.

Identity and security

Four identity tracks
Platform customers, company staff, residents with a secure link, and invited portal users, each with its own tokens and signing secrets.
Role-based staff access
Admin, operations, accounting, read-only and field-worker roles, checked at route level; portal users get a permissions allow-list.
Secure links done right
Resident links are opaque tokens stored only as HMAC-SHA256 hashes and compared in constant time.
APIs not on the internet
The FastAPI services accept only internal traffic from authenticated callers. The Next.js server calls them with a Google-signed identity token and forwards the user session in a separate header.
Strict inputs
Request models reject unknown fields, interactive API docs are disabled outside local development, and every request carries a correlation ID.

Running on Google Cloud

Cloud Run
Four services: the two APIs scale to zero and the two Next.js apps render on the server.
Cloud SQL
PostgreSQL 16 with automated backups, reached over the Cloud SQL connector.
Cloud Storage
Documents and logos through an S3-compatible storage interface, served with short-lived presigned URLs. The same interface runs on MinIO locally.
Delivery
One Cloud Build trigger per repository: every push to main builds an image tagged with the commit, stores it in Artifact Registry and deploys it. Migrations run on container start.
Least privilege
One service account per service: the backend can reach the database, the bucket and its secrets; each frontend can only invoke its own API. Secrets live in Secret Manager.

What the platform does

  • Payments with review and an auditable ledger
  • Receivables with Excel import and export
  • Requests and complaints (PQRS) with tickets
  • Tasks, field workers and an hourly calendar
  • Quotes with line items, accepted or rejected from the portal
  • Projects, vendors, expenses and inventory
  • Customer 360 view and a customer / task map
  • KPI dashboard, financial and vendor reports
  • Documents attached to any record
  • Co-ownership: units, billing runs and assemblies
  • Reservations and posts for residents
  • White-label branding per organization

Engineering discipline

Tested where it matters
230+ automated tests, including tenant isolation, plan gating and token expiry and revocation, required by the definition of done.
Schema as code
17 Alembic migrations across the two services.
Decisions written down
Architecture decision records, numbered specs and a phase-by-phase roadmap, with each module shipped as its own phase.
AI-assisted, with guardrails
Built with AI coding agents working under explicit rules: architecture constraints are enforced by a hook that blocks layer-violating code before it is written.

Stack

  • Python
  • FastAPI
  • SQLAlchemy (async)
  • PostgreSQL
  • Alembic
  • Next.js
  • React
  • TypeScript
  • Tailwind
  • Zod
  • Cloud Run
  • Cloud SQL
  • Cloud Storage
  • Cloud Build
  • Artifact Registry
  • Secret Manager
  • Docker