Most diagnostic content on the web is a wall of text about parts you've never seen. I wanted to know what happens when you treat a physical system the way we treat enterprise knowledge: build the ontology first, then let every surface — 3D scene, diagnosis engine, guided scenarios, structured data — read from the same graph.
The result is the [Interactive 3D HVAC Troubleshooter](https://venkatapagadala.com/guides/hvac-system-troubleshooting): a complete residential split system modeled in 3D, wired to a fault ontology of 39 components, 22 homeowner-observable symptoms, and 35 faults connected by implicates/presents-as edges.
The ontology is the product
Every feature is a traversal of one typed graph:
- —Explore mode renders Components — click the run capacitor and you get its role, its failure signature, and every fault that implicates it.
- —Diagnose mode walks Symptom→Fault edges: pick \"outdoor unit hums but won't start\" and faults rank by precision, recall, and a real-world service-call prior. Gas-smell and CO-alarm inputs bypass ranking entirely and render evacuate-first guidance.
- —Scenarios replay real service calls step-by-step — the attic pan visibly fills with water, the float switch rides up, turns red, and kills the system, exactly like the 24V circuit it models.
- —The five system paths (airflow, refrigerant, electrical/control, combustion, drainage) segment everything: every component belongs to a path, every fault inherits its paths, and the diagnosis tells you which flow is broken, not just which part.
What made it work
Three decisions carried the project. First, data-only ontology: the graph lives in one dependency-free TypeScript module, so the 3D scene, the ranking engine, the JSON-LD (TechArticle, DefinedTermSet, FAQPage, six HowTos), and the crawlable fallbacks can never drift apart. Second, an integrity test suite — 139 assertions that every fault references real parts, every symptom resolves somewhere, and every component is diagnosable; a typo'd id fails CI, not a user. Third, multi-persona QA: simulated review panels (Gulf Coast tech, cold-climate tech, builder, homeowner, parts counter, robotics engineer) that caught everything from inverted condenser physics to the missing garage service switch.
Where it goes next
The same graph now carries a machine layer: formal cooling/heating state machines with real timings, a 12-point telemetry registry (18–22°F delta-T, 115–140 psi suction, 8–15°F superheat), and OEM-agnostic board-code hints. That's the seed of a digital twin — bind live sensors to the ontology humans already use, and finding problems and parts in a real system becomes the same traversal.
[Open the 3D troubleshooter →](https://venkatapagadala.com/guides/hvac-system-troubleshooting)