ClearSkies Landing Page (A Crisis-to-Action Translator)
Live Dashboard (AirNow + PMS5003 + SHT31 with Freshness Labels)
Code Orange Ozone Trap (Clean Indoor PM, Elevated Outdoor Ozone)
Cited Reasoning (Why One Sensor or Web Search Isn't Enough)
Conflict Scenario (Escalating Instead of Trusting the Cleaner Reading)
Spanish Mode (Plain Language Guidance for Families)

ClearSkies

Inspiration

On a Code Orange afternoon in Edison, NJ, a parent like Maria gets two messages that seem to contradict each other: a public alert says "limit outdoor activity," but the cheap air-quality monitor in her son's room glows green. Diego is eight, has asthma, and lives in an apartment without central AC. The green light feels like permission.

That contradiction is the trap that started ClearSkies. The help Maria needs already exists: EPA guidance, AirNow readings, National Weather Service alerts, asthma guidance, and sensor data. But those sources are scattered across different systems, written for different audiences, and not designed for a parent making a decision under stress.

A web search cannot solve this because the dangerous part is not missing information. It is conflicting information. "Code Orange" says limit activity. The indoor monitor says the room looks fine. AirNow may show that ozone is elevated. Maria has to know which source matters for an asthmatic child right now.

The key insight is the ozone-blind trap. A low-cost particle sensor can detect smoke and fine particles, but it is physically blind to ozone. Ozone can drive Code Orange days in the summer, which means the day the room sensor looks safest can still be the day Diego should not be running sprints outside.

ClearSkies fits Direction A: Crisis-to-Action Translator. It turns confusing public-health information into one clear, cited action plan for a specific parent and child, and it says out loud when it cannot see the whole picture.

What it does

ClearSkies takes a vague air-quality alert and turns it into a clear, cited action plan for Diego. It combines five live and contextual inputs that no single source can provide alone:

live indoor PM2.5 from a PMS5003 particle sensor
indoor temperature and humidity from an SHT31 sensor
outdoor PM2.5 and ozone from EPA AirNow
active National Weather Service alerts
Diego's vulnerability profile: child, asthma, Edison-area ZIP, and no central AC

From those inputs, a deterministic engine assigns a risk tier from 0 to 4. The app then shows:

a plain-language verdict, like "keep hard outdoor play inside today"
a numbered checklist where every step cites an official source
an ozone-blind warning when a clean room reading could falsely reassure
an evidence panel with every reading, its source, and its freshness
a human-handoff block when symptoms appear or the air reaches the danger tier

Freshness is treated as part of the decision, not as a footnote. Every reading is timestamped, source-labeled, and either included, grayed out, or excluded. A stale indoor sensor cannot keep the tier low. Replay data is labeled as replay. Missing data never becomes "safe."

Temperature and humidity do not override pollutant risk, but they help explain whether actions like closing windows or filtering indoor air are realistic for an apartment without central AC. That matters because the best public-health advice is only useful if Maria can actually follow it.

ClearSkies is useful because it reconciles partial sources. A web search gives generic advice. AirNow gives a regional outdoor reading. A cheap room sensor gives one slice of Diego's air. ClearSkies cross-checks those sources, identifies the conflict that matters, and turns the result into one cautious next step for Maria.

The AI performs citation-bound crisis translation. It selects from a curated official guidance corpus and turns the locked engine decision into plain language a parent can act on. The deterministic engine still owns the risk tier, so the model explains the action but does not decide the danger level or make medical calls. Any checklist step without a valid official citation is dropped before it reaches the parent.

How we built it

ClearSkies runs on one safety rule: a deterministic engine sets the risk tier, and the AI explains the result under strict guardrails.

The stack is Next.js 15 and TypeScript, with Supabase Postgres and Realtime for live readings. In Diego's room, two ESP32-S3 boards stream data from a PMS5003 particle sensor and an SHT31 temperature and humidity sensor. The app cross-checks those room readings against the EPA AirNow API for outdoor PM2.5 and ozone, plus National Weather Service alerts.

We added real hardware because Maria's decision is local. A regional AQI number cannot tell her what is happening in Diego's bedroom. But the hardware also has a limitation: the PMS5003 cannot measure ozone. ClearSkies makes that limitation visible instead of hiding it.

Every reading is mapped to an air-quality category. For indoor PM2.5 (p) in µg/m³, we use a real-time action mapping that is deliberately coarser than a regulatory 24-hour average: $$ c(p) = \begin{cases} 0: & 0 \le p < 9 \\ 1: & 9 \le p < 54 \\ 2: & 54 \le p < 149 \\ 3: & 149 \le p < 249 \\ 4: & 249 \le p < 349 \\ 5: & p \ge 349 \end{cases} $$ The key idea is the relevant exposure category, (E): the risk category that actually matters for the decision in front of us. The engine computes it from category scores, not raw numbers:

$$ c_{\text{in}}=\text{indoor PM}_{2.5}\text{ category} $$

$$ c_{\text{out,PM}}=\text{outdoor PM}_{2.5}\text{ category} $$

$$ c_{O_3}=\text{outdoor ozone category} $$

Then the engine applies:

$$ E = \begin{cases} \max(c_{\text{out,PM}}, c_{O_3}) & \text{if Diego is going outside}\ \newline \max(c_{\text{in}}, c_{O_3}, c_{\text{out,PM}} - 1) & \text{if Diego is inside and the sensor is fresh}\ \newline \max(c_{\text{out,PM}}, c_{O_3}) & \text{if Diego is inside and the sensor is stale or missing}\ \newline \end{cases} $$

The most important guardrail is:

$$ E \ge c_{O_3}\quad\text{always.} $$

Because the indoor PM2.5 sensor cannot measure ozone, a clean room particle reading is never allowed to cancel out elevated outdoor ozone.

The tier follows from (E), with hard guardrails. Tier 4 suppresses the normal checklist and hands off to a human. The word "safe" is forbidden once risk is elevated. Claude Haiku 4.5 explains the already computed decision using selected official guidance. Any step it produces without a valid official citation is removed before display.

Challenges we ran into

Almost every wall we hit was a hardware ghost story, and the recurring lesson was that the part was rarely the problem.

The PMS5003 fan would not spin. Two sensors, fresh wires, and a different ESP32 all failed in the same way. It looked like dead units. The real cause was power quality: the ESP's 5V-in sagged, and a lossy cut-cable splice ate the rest. Powering the sensor from an external 5V brick with a tight splice and bonding grounds unstuck the laser instantly. Clean air read about 2 to 9 µg/m³, and live incense smoke spiked it to about 830 µg/m³ with a smooth decay.
The SHT31 looked like it was overheating. The board got hot the moment we wired the sensor. It was not a fried chip. The 4-pin header was seated down one breadboard column, shorting VIN to GND. One pin per column fixed it, and real readings of about 30 °C and 42 percent relative humidity flowed.
The ESP32 boards looked bricked. Hours of 0107 and 0105 flash failures turned out to be a bad USB cable corrupting host-to-chip data. A good cable gave an immediate "Hash of data verified."
The AI explanation layer was silently falling back. Our Claude explanation layer looked like it worked, but it was always showing deterministic fallback text. The culprit was one invalid strict: true field on the tool definition, which returned HTTP 400 and triggered the fallback. Removing it brought the real, guarded model online.

We did not replace a single component. Every "dead" sensor and "bricked" board was alive the whole time.

Accomplishments that we are proud of

0 percent false reassurance. Across 14 synthetic edge-case scenarios run through the exact engine the app uses, the single most dangerous failure mode never fired.
The ozone-blind insight, made actionable. We turned a sensor's physical limitation into the headline safety feature instead of hiding it.
A real, auditable safety architecture. The deterministic engine owns the tier, while the AI performs citation-bound crisis translation. That means the system can use AI where it helps most, but still show exactly why the safety decision happened.
Live, end-to-end hardware. Both indoor sensors run live, and a real smoke spike escalates the tier on screen with no mockups.
Honest data handling. Every reading is source-labeled and timestamped. Stale readings are excluded from the decision. Replay data is always labeled as replay. Missing data never becomes reassurance.

Impact

The better action is specific: Maria does not treat the green room monitor as permission for outdoor soccer. She limits hard outdoor play, moves activity to a lower-risk time, and knows not to rely on the indoor particle sensor for ozone.

In a five-person usability test, participants first saw only this raw information: Code Orange, Unhealthy for Sensitive Groups, and an indoor monitor reading "Good." Before ClearSkies, confidence averaged about 2.5 out of 5, and several participants said they might still allow Diego to play outside lightly or briefly. After seeing ClearSkies, all five changed to limiting or skipping outdoor play, all five correctly identified ozone as the pollutant the indoor sensor cannot measure, and confidence rose to about 4.6 out of 5. The average clarity score was 4.8 out of 5.

One parent summarized the value best: "The green indoor number would have made me feel safer than I should have. ClearSkies explained why that was a trap."

This is still a small usability test, not clinical validation, but it directly tests the failure mode ClearSkies was designed to prevent: false reassurance from a clean particle reading on a high-ozone day.

What we learned

Keep the AI away from the decision that can directly hurt someone. ClearSkies still uses AI meaningfully, but not to decide danger. The deterministic engine sets the tier, and the language model translates that locked decision into calm, cited, plain-language guidance.
Honesty is a feature. Labeling stale readings, regional-versus-room data, replay data, and the sensor's ozone blind spot is not a weakness to hide. It is the whole point.
Freshness has to be part of the safety logic. Our qualifier feedback pointed out that stale source data was a core risk. In ClearSkies, freshness is not just displayed after the fact. It affects whether a source can influence the tier.
Measure it, do not just claim it. Across 14 synthetic edge-case scenarios run through the exact engine the app uses:

$$ \mathrm{FalseReassurance}=\frac{\big|{\text{told "safe"}\ \wedge\ \text{actually unsafe}}\big|}{N}=\frac{0}{14}=0. $$

Tier accuracy was 100 percent, escalation recall was 100 percent, citation validity was 36 out of 36, ozone-trap pass rate was 100 percent, and the false-reassurance rate was 0 percent. These are synthetic stress tests of the decision engine, not clinical validation.

Responsible AI

The main risk is false reassurance: telling Maria the air is safe when it is not. The clearest failure case is a high-ozone day when the indoor particle sensor reads clean. A system that trusts the sensor alone could encourage outdoor activity for an asthmatic child at the wrong time.

ClearSkies reduces that risk in four ways. First, the deterministic engine, not the language model, sets the risk tier. Second, ozone is always included as an independent risk because the room sensor cannot measure it. Third, stale or missing data lowers confidence and cannot produce a reassuring result. Fourth, every AI-written action step must cite an official source or it is removed.

The human-in-the-loop decision is medical care. ClearSkies will not tell Maria whether to give medication, change an inhaler dose, or go to the emergency room. If Diego has symptoms or the air reaches the danger tier, the normal checklist is suppressed and the app points Maria to Diego's clinician-issued asthma action plan, emergency guidance, or a human review path. ClearSkies helps with environmental decisions. Clinical decisions stay with humans.

What is next for ClearSkies

Close the ozone blind spot in hardware. Add a dedicated ozone sensor so the room can measure what it currently has to infer from AirNow.
More rooms and more pollutants. Extend beyond one bedroom and beyond PM2.5 and ozone, including NO2 and humidity-driven mold risk.
More languages. Build beyond the current Spanish toggle so more families can act on the same plan.
A shareable, printable plan. Give parents something they can hand to a school nurse, coach, or clinician.
Smarter retrieval. Move from curated guidance selection to embeddings-based retrieval so the explanation layer can ground advice in a larger official library.
Change alerts. Push a notification the moment the tier changes instead of waiting for the parent to check.
Wider user testing. Work toward real-world validation without claiming it too early.