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 26)
27
Shipped changes
400+
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 — can also be dispatched to jobs
T1AdminFull office nav; HR, System, Agents
T2Office ManagerOffice operations incl. full Finance; no HR or system admin
T3Strategy ManagerDashboard, search, Finance (read-only), 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
The Company Wide Schedule 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. Eight boards — Residential kanban, AHS warranty authorizations, Preventive Maintenance cycles, Projects timeline, PHDC city work, ECA agency 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 day and a 2, 4, or 8-hour block sized by the service type.
Eight work-stream boards with drag-and-drop scheduling — ECA agency work now routes to a board of its own
The Company Wide Schedule: every department's schedule on one read-only calendar with click-to-preview, pinned above every schedule board and on the dashboard
Residential kanban runs five lanes, including Needs Authorization for jobs waiting on a parts decision
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
Lead promotion asks which pipeline (Residential, AHS, PM, PHDC, ECA), prefills the form, and writes nothing until a person confirms
The work-order page is a desk: an 8-stage pipeline rail with interrupts drawn on the current rung, plus Overview, Activity, Parts & POs, Documents, and Finance tabs
Office-only 12-check verification panel on every work order — advisory today (it reports, it does not block completion), and legacy completed jobs are labelled never verified
Field lock: the office owns a job until the technician taps En route — then assignment, type, and slot freeze at the database itself
Labor cost (technician day rates) visible to office tiers only
Boards refresh themselves in realtime when the data changes
A job's life
Enquirywebsite / phone / AHS
Triagehuman review
Work orderbooked into a slot
Field visittech PWA
Signed closeoutsignature on glass
Invoicepriced & sent
Not built yet — said plainly
The office verification checklist reports but does not enforce: it blocks neither completing a job nor billing it, and it lives only in the app — a direct write or an offline replay never meets it. Making it a database gate is a later phase
No decline button on a part request — authorizing raises the purchase order, but refusing one is a conversation outside the app today
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
Container lanes now cover AHS, Residential, and Preventive Maintenance — PM visits file into a container like every other lane
Not built yet — said plainly
The PM container is seeded, but service agreements are still empty — the PM pipeline has no visits to generate yet
Finance is now Quality Air's own double-entry general ledger — a 56-account HVAC chart, an immutable journal where mistakes are corrected by reversal rather than edit, and P&L, balance sheet, trial balance, and cash flow drawn from our own book. QuickBooks is downstream now: kept fed until it can be retired (the readiness panel reports 3 of 5 checks). Outbound money is still customer invoices priced at company standards ($125/$165 service calls, free estimates); inbound is still supplier bills parsed out of Gmail by AI and human-approved — but approval now posts a journal entry to our ledger, and QuickBooks receives a push.
Automatic posting: invoice approved, customer payment, vendor bill approved, vendor-bill payment — each mints its journal entry
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
Period and fiscal-year close with locks — a closed period refuses new entries
A/R aging that trusts QuickBooks's own balances and excludes settled invoices ($1.3M across ~900 invoices, back to 2023) + A/P aging
Bank statement import (CSV/OFX) with coding rules and reconciliation
Job profitability per work order; P&L by job type and period
PA/Philadelphia sales-tax liability accounting; fixed assets with straight-line depreciation
QuickBooks push, per-entry or bulk — a human button, journal-only entry types, gated on full account mapping and a realm guard (invoices and bills already cross as documents)
The old QuickBooks mirror screens remain as the tie-out comparison
Full transaction explorer with saved views
Vendor directory with every original invoice PDF archived
A supplier bill's path
Gmailinvoice PDF arrives
AI parseGemini reads lines
Pending billin review queue
Human approvaloffice signs off
Our ledgerjournal entry posts
QuickBookspushed downstream
Not built yet — said plainly
Historical posting catch-up is still running — 1,035 entries posted so far, roughly 868 historical invoices to go (the totals grow as it's worked)
AHS jobs bill $0. An AHS work order's invoice is raised at zero and stays there — skipping the $125/$165 service-call fee is correct (AHS pays the claim, not the homeowner), but nothing copies the authorized claim amount onto the invoice, and the generate-from-logged-work automation deliberately refuses to run on AHS invoices. Customer upcharge has the same gap. Someone has to add the lines by hand
That $0 then propagates: the ledger skips a zero invoice, so an AHS job produces no journal entry and never reaches the statements or the QuickBooks push — and because the unposted-work summary also filters out $0 invoices, the missing revenue isn't flagged as missing either. The authorized amount itself is real and tracked; it drives Finance → AHS Control and its budget-band metrics. It just never becomes revenue
No posting engine yet for payroll, credit memos, or AHS claims — those take hand journal entries today
/warehouse (+ purchasing) · /vehicles · /pricebookOffice (vehicles also Field Manager)
Physical stock across the warehouse and every van, with technician replenishment requests and transfers. Purchasing runs the purchase-order queue — draft to issued to received — born from authorized field part requests. 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
Purchasing: the PO queue from draft → issued → received, with the open commitment visible; vendor by link or free text — and honestly, Issue to vendor records the state, it does not email or transmit anything
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 — one phone column at every width, behind its own sign-in cover — that keeps working with no signal. Assigned jobs with routing and contact buttons, one-tap arrival, photos, part requests in the tech's own words, 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 — with a solid-red Offline chip and a keep-working banner so nobody panics
Truck gate: pick your truck (A1/B1/C1) before starting a job — enforced by the database, and the picker works offline and remembers your last truck
Arriving is starting: one tap moves the job to In Progress, unlocks notes, parts, and photos, and stamps arrival and start together
Part is needed: the tech describes the part in their own words — the job moves to Needs Authorization, no invoice is raised, and the office decides
Truck tab: weekly check-in (odometer, fuel, condition — the only mileage collected) plus fault reports
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
Crew/Me toggle and a per-technician page — current job, stats, van stock
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. Live AI workers today: the maintenance crew, which inspects the data every morning, auto-fixes what is safe, and escalates the rest to the Activity Rail; the QA Concierge, which interviews website visitors and files sales enquiries into the pipeline on its own; and the nightly finance team — Bookkeeper, Controller, Collections, and CFO analyst — which suggests and drafts while humans approve.
Daily crons before office hours: QuickBooks sync, maintenance scan, PM-visit generation, Gmail vendor-bill ingest — plus careers exams every 10 minutes
Nightly finance run: posts pending journal entries (500 a night), then the team works — the Bookkeeper suggests bank codings but never posts, the Controller runs deterministic checks with no AI model at all, Collections drafts dunning into the approval queue and sends nothing, and the CFO analyst chats over deterministic report calls
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
Most of the fourteen roster entries still await their release wave — the workers running live today (maintenance crew, concierge, finance team) grew up beside that plan, not out of it
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 (+ imports, 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
Import Conflicts: jobs pulled from the old dispatch system stage in a conflict queue instead of being trusted — a match ladder (dispatch id → AHS # → PHDC # → address+date), side-by-side review with conflict chips, and the office ticks which facts to take. It enriches matched jobs only — it never creates work orders, and unmatched jobs are decided by hand
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
Import Conflicts admits only T0/T1 today — T2 admission is a known gap
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 26 · 27 build days · 400+ 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.
Jul 25
Our own books
Finance became Quality Air's own double-entry general ledger: a 56-account HVAC chart, an immutable journal corrected only by reversal, period close with locks, bank import and reconciliation, job profitability, and financial statements drawn from our own book. QuickBooks moved downstream — kept fed by a human-button push until it can be retired. Honestly told: the historical catch-up is still running, and payroll, credit memos, and AHS claims still post by hand.
Jul 26
The field takes command
The technician app got its own front door, a truck gate (pick A1, B1, or C1 before starting — the database insists), and one-tap arrival that starts the job. The office owns a job until the tech taps En route, then the booking freezes. A part request in the tech's own words now runs Needs Authorization → purchase order in Warehouse Purchasing. The work order became a desk — pipeline rail, five tabs, advisory verification — Dispatch gained the ECA board and the Company Wide Schedule, and old dispatch.me pulls now settle in an Import Conflicts queue instead of being trusted.
