ES

Field Operations Platform

Role
Design & build
Type
Production
Focus
Full-stack platform

Operations software for an engineering services company in Colombia: client equipment and maintenance alarms, work orders run by technicians on their phones and signed on site, quotes, receivables and PDF service reports, plus a portal where clients follow their equipment, requests and balances. In production on Google Cloud.

Request path in production

  1. web app or phoneNext.js, JWT
  2. FastAPIcorrelation ID, validated DTOs
  3. auth and scoperole, technician and partner scope
  4. domain serviceorganization check, state machine
  5. repositoryasync SQLAlchemy, PostgreSQL
  6. side effectsemails, notifications, PDFs in background

Three apps, one backend

Back office

Staff

Clients, equipment, suppliers and catalogues; operations, projects, quotes, receivables, reports and a live map of technicians and clients.

Technician app

Mobile web

Assigned work orders with check-in and check-out, evidence photos, dynamic forms and two signatures, and it keeps working without signal.

Client and partner portal

Self-service

Equipment, service requests, complaints (PQRS), quotes to approve and account balances.

API

FastAPI on Cloud Run

One backend for the three apps, with separate identities for staff and portal users.

Architecture decisions

Work orders as a state machine
Pending → assigned → in progress ⇄ paused → executed → finished → closed. A job cannot finish without start and end photos, the required form fields and two signatures: the technician’s and the client’s, with the signer’s name.
Finished means locked
A finished job is read-only for technicians, writes a row to the equipment’s history and emails the client the PDF report.
Tickets with transitions per actor
Staff drive most of a request, technicians only the execution steps, and the client approves or rejects the quote.
Data scoped to the organization
Every record carries its organization; a mismatch is answered as not found, and isolation has its own tests.
Two identity systems
Staff and portal tokens are signed separately, and a portal token is bound to exactly one client or one partner.
Roles plus overrides
A role-based permission matrix with per-user overrides; technicians only see their own work and partners only the clients assigned to them.
Side effects off the request
Audit emails, portal notifications and PDF attachments run as background tasks after the response.
Layers that stay layers
api → domain → data, with one error contract, and a hook that blocks code breaking the layer rules before it is written.

Built for the field

Works without signal
Forms keep a local snapshot, a draft and a queue of pending changes that sync when the phone is back online, with a visible status.
Signatures on the phone
Technician and client sign on screen; the signatures are stored with the job and printed on the report.
Dynamic forms
Staff design inspection forms from a schema builder, per type of job, without a deploy.
Live alarms and map
Maintenance alarms arrive over server-sent events, and a location heartbeat (with permission) feeds a live map.

Documents and money

Quotes and receivables together
Approving a quote creates its receivable in the same transaction; payments and credit and debit notes follow.
PDF reports
Quotes, service reports and financial reports rendered from HTML templates.
Excel in and out
Bulk import and export, protected against formula injection.
Scheduled jobs
A daily scan for maintenance alarms, marking overdue receivables and one-time reminders at 30 and 90 days.

Running on Google Cloud

Cloud Run
API and web app as separate services.
Cloud SQL
PostgreSQL 16, with migrations applied through the Cloud SQL proxy as a step of every deploy.
Cloud Storage
Photos, signatures and PDFs behind a storage interface, served with signed URLs.
Delivery
Cloud Build on every push to main: build, push to Artifact Registry, migrate, deploy. Secrets live in Secret Manager.
Scheduler
In the cloud, an external scheduler calls a secret-protected internal endpoint instead of running jobs inside the web process.
Email
A pluggable provider (API, SMTP or a local mode that writes the HTML to disk for review).

Engineering discipline

Tested
434 backend tests passing in the latest run, written test-first, plus unit tests on the web side.
Schema as code
32 Alembic migrations.
Written down
Phase roadmaps, feature specs and bug post-mortems kept with the code.
Tooling
Ruff on Python, strict TypeScript on the web app.

Stack

  • Python
  • FastAPI
  • SQLAlchemy (async)
  • PostgreSQL
  • Alembic
  • WeasyPrint
  • Next.js
  • React
  • TypeScript
  • Tailwind
  • Zod
  • Google Maps
  • Cloud Run
  • Cloud SQL
  • Cloud Storage
  • Cloud Build
  • Docker