Field Operations 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
- web app or phoneNext.js, JWT
- FastAPIcorrelation ID, validated DTOs
- auth and scoperole, technician and partner scope
- domain serviceorganization check, state machine
- repositoryasync SQLAlchemy, PostgreSQL
- 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.
- 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.