Property Management SaaS
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
- browserNext.js app
- Next.js on Cloud Runpublic, server-rendered
- server-side proxyadds a Google-signed identity token
- FastAPI on Cloud Runinternal ingress only
- 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.