Orbit Work Order Platform
Orbit (codebase: mars_workorder_system) is Wasteology's work order management platform for the Frontline Solutions Services (FSS) team. It provides a centralized dashboard and communication layer between customers, Wasteology dispatchers, and haulers — covering the full WO lifecycle from haul request through compliance document verification and payment.
ADO Repo: dev.azure.com/wasteology/Wasteology/_git/mars_workorder_system
Core Capabilities
| Feature | Description |
|---|---|
| Active Queue | High-density WO table with fuzzy search, real-time status, recurring rolling window filter |
| Progress Tracker | Visual stepper showing the real-time stage of any work order |
| 5-Dot Compliance | LSP / DSP / BOL / COD / TON documentation indicators per WO |
| State Machine API | Advance, bounce-back, and cancel with gate enforcement (quote gate, compliance gate) |
| Multi-Party Personas | Separate shells for customer (Bosco/Travis/All Sites), Wasteology FSS dispatcher, and hauler |
| Hauler Portal | Dedicated hauler sub-app at /h/ — queue filtered by vendor, history, WO detail |
| Quote / NTE Approval | Customer-facing quote approval with NTE ceiling enforcement and overage authorization |
| Threaded Chat | Embedded communication loop with unread message tracking per WO |
Environments
| Environment | Backend API | Database | Purpose |
|---|---|---|---|
| Dev | orbit-backend-dev (orbit-rg-dev) | orbit_dev (pg-wasteology, password auth) | David English + Shane St. Clair — daily development |
| Sandbox | orbit-backend-sandbox (orbit-rg-sandbox) | orbit_sandbox (pg-wasteology) | AI agent pipeline output + human preview before prod |
| Prod | orbit-backend-prod (orbit-rg-prod) | orbit_prod (wg-pg-orbit-prod, Entra-only auth) | Customer-facing — human sign-off required for any deploy |
Frontend: orbit-prod-web Azure Static Web App — auto-deployed on push to main. PRs get ephemeral staging slots.
See the Environment Guide for a full visual map of environment usage, sandbox data strategy, and the AI agent sandbox pipeline.
Tech Stack
Frontend: React 19, Vite, React Router 6, pure CSS design tokens, Lucide React, Recharts, Vitest
Backend: Python 3.12, FastAPI, SQLAlchemy async, asyncpg, Alembic, Pydantic, azure-identity
Infrastructure: Azure Container Apps, Azure Container Registry, PostgreSQL Flexible Server, Azure Key Vault, GitHub Actions OIDC (sandbox/prod deploys)
Database Access
orbit_prod uses Entra-only auth — no static passwords. database.py automatically injects a fresh Azure token via DefaultAzureCredential; developers only need to run az login once.
| User | Role | DATABASE_URL |
|---|---|---|
| David English | orbit_rw | postgresql://DEnglish@wg-pg-orbit-prod.postgres.database.azure.com/orbit_prod?sslmode=require |
| Shane St. Clair | orbit_rw | postgresql://Sstclair@wg-pg-orbit-prod.postgres.database.azure.com/orbit_prod?sslmode=require |
| Kent Gray | Admin | postgresql://orbit-prod-db-admins@wg-pg-orbit-prod.postgres.database.azure.com/orbit_prod?sslmode=require |
orbit_rw grants SELECT / INSERT / UPDATE / DELETE on all public tables (current and future via ALTER DEFAULT PRIVILEGES).
ADW Development Workflow
All features are delivered through the Agentic Development Workflow (ADW) — a 7-step loop from spec to production:
1. /spec-create → branch, number, template
2. /spec-review → architect validates spec completeness
3. /spec-dispatch → ADW agent implements the spec
4. /spec-validate → Playwright MCP validates against sandbox
5. Human review → kgray signs off on PR
6. Merge to main → GitHub Actions deploys to sandbox then prod
7. /spec-promote → marks spec validated, closes loop
See the ADW Workflow guide for the full pipeline.
Spec Tracker
| Spec | Title | Status |
|---|---|---|
| 01 | ADW Workflow Initialization | ✅ Approved |
| 02 | Backend Skeleton | ✅ Approved + Deployed |
| 03 | GitHub Actions Deploy Pipeline | ✅ Approved + Deployed |
| 04 | Frontend API Integration | ✅ Implemented + Validated |
| 05 | Authentication (Azure AD / Entra JWT) | ✅ Implemented + Validated |
| 06 | State Machine API | ✅ Implemented + Validated |
| 07 | Compliance Document Upload | 🗓 Planned |
| 08 | Hauler Notifications | 🗓 Planned |
| 09 | CieTrade Sync | 🗓 Planned |
| 10 | Red Team QA — Pre-Release Gate | 🗓 Planned |
Key Documents
| Document | What's in it |
|---|---|
| 🗺 Environment Guide | Visual environment map, sandbox data strategy, AI agent sandbox pipeline swimlane |
| 🚀 Development Roadmap | Spec tracker, phase roadmap, Red Team QA design, release readiness gate |
| 💵 QuickBooks Billing — Status & Decisions | QBO invoicing integration — what's built (create-invoice live, charge-driven model behind a flag), the GL/tax decisions with live status, and open questions for finance/tax/billing-ops review |
| 🐞 UAT | UAT hub — scenario catalog, execution log, and findings dashboard |
| 💰 UAT Cost & ROI — ADW vs a Human Team | Cost/ROI companion to the UAT suite — the Mars Work Order build priced two ways (ADW/agent-driven vs. a conventional human team) with a side-by-side effort and cost breakdown |
| 🛟 Disaster Recovery Runbook | RTO/RPO targets, backup posture, and step-by-step restore procedures for the Orbit prod DB and app tier |
| 📊 ADW ROI — The Mars Build, Priced Two Ways | ROI case study pricing the Mars Work Order System (Orbit pilot) two ways — the ADW/agent-driven build vs. a conventional human build — with side-by-side cost and effort tables |
Individual spec HTML files live in specs/ in the ADO repo — open any .html in a browser to read the full spec.