Quality Air OS is the company's operating system: dispatch, sales, estimating, billing, inventory, fleet, HR, training, and the customer portal — one codebase, one database, one set of rules. This page is its living blueprint: every department drawn brick by brick, what it does, who can touch it, and how the internals fit together. It grows with the build.
Departments & modules
24+
Web surfaces on one deploy
5
Access tiers (T0–T9)
11
Build days (Jun 5 → Jul 24)
25
Shipped changes
370+
AI providers routed by task
7
One building, five doors
Five surfaces on one deploy
Everything below is a single application and a single database. Which door you walk through is decided by the web address — and every door opens onto only its own rooms. An address the system doesn't recognize gets a dead-end login page, never the office.
One codebase · one database
host-routed, fails closed
Office consoleadmin.qualityairhvac.comThe full command center — every department below.Owner, admins, office, strategy, sales, CSR
Field apptechnician.qualityairhvac.comOffline-capable job PWA: jobs, van stock, signatures.Technicians & field managers
Client portalclientlogin.qualityairhvac.comRead-only project window + service requests.Invited customers only
Training hubtraining.qualityairhvac.comCourses and the interactive 24V controls lab.Learners (techs + managers)
About OSaboutos.qualityairhvac.comThe living blueprint of the whole system.Leadership — this page
How it's built
The architecture, layer by layer
From the screens down to the database, each layer has one owner and one job. The security layer is the important one: the database itself enforces who sees what, so the rules hold even against a mistake in the screens.
Surfaces
Five host-routed web surfaces on one Next.js deploy — unknown hosts fail closed to a dead-end login, never the office app.
Office consoleField PWAClient portalTraining hubAbout OS
Application
Next.js App Router on Vercel. Server components joined to live data; realtime boards re-render on database change.
Server renderingRealtime boardsPrint-to-PDF surfacesEdge middleware guard
Data & security
Supabase Postgres. Row-level security is the real enforcement — the database itself refuses what a role shouldn't see, so the rules hold even against a UI mistake.
Row-level security11-tier role enumAudit trailsFrozen snapshots for documents
AI layer
A task-routed model gateway: each job type goes to the model best suited for it, with an automatic fallback chain. Sensitive personal data is pinned to local models and never leaves the building.
Every person in the company — and every customer — holds exactly one tier. The tier decides which surfaces exist for them, which departments appear, and which rows of data the database will even return. Pay data, for example, is refused below admin level by the database itself.
T0Super Admin (owner)Everything, incl. owner-only Assembly and Team & Access
T1AdminFull office nav; HR, System, Agents
T2Office ManagerOffice operations; no finance, HR, or system admin
T3Strategy ManagerDashboard, search, Finance, Help — the numbers view
T8Sales Team MemberSales only, scoped to their own deals
T9Customer Service RepDispatch scheduling, no financials
Brick by brick
Every department, fully drawn
Each card is one department of the OS: what it does today, who can open it, the path work takes through it, and — held to the same honesty rule as the in-app guides — what is deliberately not built yet.
Command
Dashboard & Search
/dashboard · /searchOffice T0–T2 + Strategy T3
The morning command brief: pending approvals, today's jobs, 30-day revenue, system health, and a live read-only schedule board. Beside it, one fuzzy search box that looks across customers, projects, work orders, vendors, parts, and the company Google Drive at the same time.
Approvals, today's jobs, and 30-day revenue at a glance
Live schedule board embedded read-only at the bottom
One search box across six record types plus Google Drive
System-overview walkthrough video for onboarding
data: work_orders · invoices · approval_queue
Operations
Dispatch
/dispatch (+ ahs, leads, preventive-maintenance, phdc, subcontractor)Office + Field Manager; Sales Manager & CSR see the board (CSR schedules, no financials)
The heart of daily operations. Seven boards — Residential kanban, AHS warranty authorizations, Preventive Maintenance cycles, Projects timeline, PHDC city work, Website-lead triage, and customer Portal requests — each with a real day timeline (8am–6pm by technician row) and a month load grid. Every job books into a slot sized by the work.
Seven work-stream boards with drag-and-drop scheduling
The Global Board: every department's schedule on one read-only calendar with click-to-preview, on /dispatch and the dashboard
Day timeline by technician + month load grid, all streams at once
Website enquiries land in a triage queue — humans promote real ones to work orders, bots never reach the board; QA Concierge chats arrive tagged with type and urgency, and its sales enquiries route themselves to the pipeline
Work-order detail page is the job's single source of truth: events ledger, parts, crew, subcontractor assignments
Labor cost (technician day rates) visible to office tiers only
Boards refresh themselves in realtime when the data changes
A Monday-style pipeline board: nine stages across four phases (Lead → Sales Team → Closing → Scheduling), with the legal stage moves enforced by the database itself. Every deal carries a Slack-style thread where stage changes, assignments, and scheduling log themselves automatically.
Drag-and-drop pipeline; illegal stage jumps refused at the database layer
Per-deal thread with auto-logged events and team messages
AI sales-estimate chatbox grounded on spec catalogs — it can never see costs or markup
Sales reps see only their own portfolio (row-level security, not UI filtering)
Closed deals convert to installation work orders; manager reviews the closeout
Printable customer estimate and signed closeout documents
Send Client Portal sign-up straight from a sold deal — the customer record, project container, and magic-link invite are created in one motion
data: sales_orders · sales_order_events · sales_estimates · sales_notificationswired to: Claude (sales chat) · Resend (invites & notifications)
Revenue
Estimator
/estimatorOffice T0–T2
A conversational estimate builder run by a four-agent AI team, each in its own colored bubble: Parts Scout extracts the equipment, Price Analyst reports what Quality Air actually paid last (it cannot invent a number), Estimate Builder writes the lines, and Margin Reviewer checks every line against the company's pricing standards.
Chat-built estimates priced from real ingested cost history and HR day rates
Voice dictation — talk the estimate in, with a live level meter
Vendor quote PDF upload: AI reads the quote, you review the extraction, it lands in quoted-price history
Margin & markup as deterministic commands that reprice the whole estimate
/customers · /warranty/ahsOffice + Field Manager (customers); office only (warranty)
The master customer directory — 3,000+ customers mirrored from QuickBooks — where each customer is a hub holding their properties, equipment, work orders, quotes, invoices, and service agreements. Beside it, the home-warranty ledger: AHS claims keyed to the 8–9-digit dispatch number, with scorecards, budget periods, and a per-customer document cabinet.
Customer hub: every property, unit, visit, and dollar in one place
Portal invites issued from the customer page (invite-only, magic link)
AHS dispatch number enforced one-per-work-order by the database
Warranty scorecards and budget-period tracking per partner
Three books that keep commercial work honest: the GC contractor book (contract value, retention held, receivables, insurance expirations), the separate municipal cabinets for PHDC and ECA city work, and the project book that rolls every crew visit, document, and purchase order up into cost, margin, and retention per project.
Contractor pipeline with COI/insurance expiry tracking
City contracts kept structurally separate from GC work
Per-project rollups: cost, margin, retention, AR
The project container is the customer's truth; the work order is the job's truth — every dollar attaches to both
Money moves in two directions and both run through here. Outbound: customer invoices priced at company standards ($125/$165 service calls, free estimates) and sent. Inbound: supplier bills arrive from Gmail already parsed by AI, get a human approval, then post to QuickBooks and fold into the job's true margin. Finance is the QuickBooks mirror — P&L by job type, a full transaction explorer, AR/AP.
Two-step vendor-bill approval before anything posts to the ledger
The Approval Gate: automation prepares actions, only an authorized person can approve them — enforced in the database
P&L by job type and period, driven by item→job-type mapping
Full transaction explorer with saved views
Vendor directory with every original invoice PDF archived
/warehouse · /vehicles · /pricebookOffice (vehicles also Field Manager)
Physical stock across the warehouse and every van, with technician replenishment requests and transfers. The truck roster gives each vehicle its maintenance history, fuel log, insurance policy link, and cost-per-mile. And seven price books — from the company flat-rate catalog to years of real purchase history read out of supplier invoices to the penny — plus four manufacturer spec catalogs beside them.
Warehouse + van stock, transfers, counts, reorder points
Dollar backlog: parts read off supplier invoices, drawn down onto jobs
Truck check-ins, maintenance programs, insurance linked to real policies
SupplyHouse history to 2019, TOSOT, DN Supply counter tickets, Associated Refrigeration (586 invoices, 2024–2026) — actual paid prices
/hr (+ employee pages)Admin only (T0/T1) — holds pay and personal data
The employee book: profiles, day rates, document cabinets, a company-history timeline on every file, and each person's training record. The careers pipeline receives applications from the public website and emails a level-matched knowledge exam about half an hour later — graded server-side, one submission per application, the applicant never sees the score — landing results in an applications queue for review.
Employee directory with pay data gated at the database layer, not just the UI
Subcontractor vendor records: trade, COI, license, rates by work stream
Careers: application → level-matched exam emailed ~30 min later (no timer on the exam itself) → graded server-side into the queue
All-tier employee intake — one door for hiring every role from laborer to sales manager, with privileged roles gated to admins
Employee dashboards show exam, training, and lab results together
Built like a safety document, because it is one. Course material is drafted by an AI author that may only draw on approved sources and refuses safety topics outright, deferring to a qualified human. Everything passes three independent review gates enforced in the database: an author cannot review their own work, an approval is bound to the exact words it was given, published material is frozen, and history cannot be edited — even by the system itself.
AI course authoring bound to licensed/public sources only
Three independent, database-enforced review gates before release
Learner hub with the interactive 24V controls lab — wire it, energize it, meter it
The lab refuses to let you move a wire on a live circuit — that reflex is the training
A lab can never record itself as permission to do real work — that field is pinned shut
Material's path to a learner
Approved sources
AI authorrefuses safety topics
Gate 1 · 2 · 3independent reviews
Frozen publishversioned
Learner hubcourses + lab
Not built yet — said plainly
Scored-evidence recording is deliberately still closed until its own tests pass — the lab coaches, it cannot yet manufacture evidence about anyone
data: training_courses · training_course_versions · training_reviews · training_lab_resultswired to: Claude (curriculum author)
The technician's whole day in a phone-first app that keeps working with no signal. Assigned jobs with routing and contact buttons, status transitions, photos, part usage from van stock, and a checklist closeout that captures the customer's signature on the glass — everything syncs itself when the connection returns.
Offline-capable: capture everything in a basement, sync on reconnect
Job detail: route, call, text, notes, photos, equipment, parts
Signature closeout checklist on the customer's doorstep
Van stock view with one-tap replenishment requests
clientlogin host — /portalInvited customers only (T6), magic-link sign-in
A private, read-only window onto the customer's own project: plain-language status, the visit timeline, photos and documents — shown only once the office marks them visible. The database itself guarantees one customer can never see another's work. The single write path is submitting a service request.
Invite-only by standing rule — no self-signup exists
Office controls visibility of every photo and document
Service-request submission — the portal's one write path; requests mint real work orders, and the customer's status chip follows the actual booking automatically
Where years of imported QuickBooks history get compiled into the operating record. The reconciliation gate stages imported customers, invoices, and projects, matches them, and publishes to the main system. The assembly workbench then mints work orders from historic invoices — a queue, a project cockpit, and an evidence tray — so every dollar ever earned lands on the visit that earned it.
Three matching gates connect staged QuickBooks data before anything goes live
Mint work orders from historical invoices with evidence attached
PHDC / ECA agency pipeline boards
Ongoing AHS work-order backfill enriches the record job by job
A roster of fourteen named background agents — billing prep, communications, routing, inventory, marketing and more — governed by one principle enforced in the database: automation prepares, a person approves. Two AI workers run live today: the maintenance crew, which inspects the data every morning, auto-fixes what is safe, and escalates the rest to the Activity Rail — and the QA Concierge, which interviews website visitors and files sales enquiries into the pipeline on its own.
Daily crons before office hours: QuickBooks sync, maintenance scan, PM-visit generation, Gmail vendor-bill ingest — plus careers exams every 10 minutes
Hermes — the read-only staff assistant that knows the business, grounded on the live database and company Drive
Approval Gate on every agent action that would touch the real world
Not built yet — said plainly
13 of the 14 agents are roster entries awaiting their release wave — only the maintenance crew runs live today
RingCentral comms pipeline is structurally present but not fully wired (planned as the CSR agent's channel)
data: agent_activity · approval_queuewired to: QuickBooks · Gmail · Google Drive · Resend
Governance
System, Help & Governance
/system · /system/sops · /help · /departmentsSystem: admin. Help: office, sales & field-manager tiers (techs get /guide in the field app)
Team & Access is where the owner grants tiers — the same ladder the database enforces. Integrations health shows Gmail and QuickBooks status with one-click reconnect. The Help Center is the in-app operating manual: tier-filtered guides for every module, with a CI test that fails the build if a module ships without documentation.
User & tier administration with an audit trail
Integration health + reconnect without a developer
Sales SOPs: six read-only playbooks (growth roadmap → compliance) rendered from version-controlled documents — readable by admins, the office manager, and the whole sales division
Not built yet — said plainly
System → Audit Logs screen not built yet
Marketing module is a placeholder shell — real lead handling lives in Dispatch → Leads
From a baseline app to a connected command system with a live data spine and an automation layer. Jun 5 → Jul 24 · 25 build days · 370+ ships.
Jun 5–6
Foundation
The live app and its core: dispatch board, sales, contractor projects, customers, and the role-aware shell.
Jun 23
Roles + Help Center
Tiered access (office, staff, field) and the in-app Help Center with contextual guides and a coverage test that keeps documentation in lockstep with the build.
Jun 24–25
Costing, Drive & the QuickBooks pipeline
Technician day-rate labor costing, Google Drive document sync, work-order numbers and crew rates, and the vendor-bill → QuickBooks groundwork.
Jun 26
The data spine — 53 ships in one day
QuickBooks connected read-only (3,000+ customers, the full ledger), the reconciliation gate, the AHS lane, smart fuzzy search, and Hermes — the read-only assistant that knows the business.
Jun 27
Automation & reliability
A background maintenance crew that inspects the data, auto-fixes safe issues, and escalates the rest to the Activity Rail.
Jul 2–3
The assembly workbench & real rates
Every dollar QuickBooks imported now gets compiled into the visit that earned it. Quality Air's real pricing standards went in behind it — $125 residential and $165 commercial service calls, free estimates. Dark mode landed the same day.
Jul 6–7
Trucks, supplier bills & the money loop
Each truck grew its maintenance history and insurance link. Supplier invoices now run a two-step approval into QuickBooks, folding true cost into each job's margin. An integrations screen shows Gmail and QuickBooks health.
Jul 10
The clock comes to dispatch
A real day timeline — 8am to 6pm by technician row, jobs booked into slots sized by the work. New projects file themselves into the right lane automatically.
Jul 15
Website leads & the full schedule
Website enquiries land in a triage queue — the office promotes the real ones and bots never reach dispatch. The board gained a month load grid showing every stream at once.
Jul 17–18
The client portal & a signed close-out
Customers can be invited to a private, read-only portal that follows their own project. Technicians close jobs through a checklist that captures a signature on the glass and works with no signal. Both surfaces got their own web addresses.
Jul 19
Vendor intelligence — years of purchasing, priced
The pricebook grew from three books to six: SupplyHouse orders back to 2019 at the price actually paid, TOSOT equipment, DN Supply counter tickets read line by line. 200+ historical vendor bills archived with their original PDFs. The estimator team went live the same day.
Jul 20
Training — built like a safety document
The largest single day of the build. A governed training platform where AI-drafted material must pass three independent, database-enforced review gates; a working interactive 24V lab that refuses unsafe moves; and rules that hold even against the system itself.
Jul 22–24
The sales division & the global board
Three new roles joined the ladder — Sales Manager, Sales Team, and CSR — with a nine-stage pipeline board, per-deal threads, an AI sales chatbox that never sees costs, and a printable signed closeout. Dispatch gained the all-departments global schedule board in the animated brand frame. The estimator learned margin as a command and exact-cents precision.
Jul 24
Careers, quotes & a voice
The careers pipeline went live: an application from the website triggers a level-matched knowledge exam, emailed about half an hour later and graded automatically into an HR queue. The estimator learned to read vendor quote PDFs into quoted-price history and to take estimates by voice dictation. The client portal entered phase 3 — home, visits, equipment, service requests, account. And this page — the About OS — became the system's living blueprint.
Jul 24
The concierge takes the front door
The QA Concierge replaced the website's contact form: an AI assistant that interviews the visitor, then files the enquiry itself — sales enquiries become Lead-stage deals in the pipeline with the transcript attached and the sales managers notified; service enquiries wait in the triage queue for a person. A finished conversation is never dropped, even when the AI cannot classify it. The same day, six sales SOPs — growth roadmap through Philadelphia compliance — went in as read-only, version-controlled playbooks under System.
