HSH-1011 - Building in Public with Honest Failure States

Living Document Notice
Published 2026-09-19. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Building in Public with Honest Failure States

Summary

Software development in the modern web ecosystem often conflates launch velocity with aggressive self-promotion. Early betas are frequently marketed with inflated promises, while engineering realities—flaky network connections, upstream API rate limits, and imperfect sensor coverage—are masked behind infinite spinners and synthetic animations. When an upstream data provider experiences an outage, conventional interfaces conceal the failure, leaving users guessing whether their hardware, internet connection, or application is broken.

With the release of Hushwire Beta 0.1, we have chosen a different approach: building in the open with honest, unvarnished failure states. When upstream aviation feeds drop packets, Hushwire displays the disruption plainly. When geographic constraints are reached, the boundary is explicit. Building a durable ambient instrument requires resisting feature bloat, acknowledging operational trade-offs publicly, and honoring user trust through transparent engineering. This retrospective shares lessons learned during the Beta 0.1 release cycle.

The Temptation of Opaque Error Masking

In modern user experience design, developers are often taught to hide system errors at all costs. The conventional wisdom advocates:

• Replacing failed network requests with indeterminate pulsing skeleton loaders.
• Falling back to stale cached data without informing the user that the data is five hours old.
• Showing vague messages (“Something went wrong! Check back soon.”) that provide zero actionable diagnostic context.

In entertainment applications, this masking is harmless. In an observatory instrument, however, opaque failure states break operational trust:

[ Traditional Opaque UI ] ──► Upstream API 502 Outage ──► Indeterminate Loading Spinner
                                                                   │
                                                      User wonders: "Is my Pi frozen?"
                                                      "Did my Wi-Fi drop?"
                                                      "Is the receiver offline?"
                                                                   ▼
                                                      Frustration & Wasted Diagnostics

[ Hushwire Transparent UI ] ──► Upstream API 502 Outage ──► Explicit Diagnostic Banner
                                                                   │
                                                      "UPSTREAM_GATEWAY_TIMEOUT (502)"
                                                      "Next retry in 4s | Local clock OK"
                                                                   ▼
                                                      Immediate Operator Clarity

Designing Honest Diagnostics

Hushwire treats connection health as a first-class citizen of the user interface. The radar sweep perimeter and status indicators communicate network conditions clearly without creating panicked red popups:

┌─────────────────────────────────────────────────────────────┐
│ STATUS: UPSTREAM_TIMEOUT (HTTP 502)                         │
│ RETRY: 04s | LATENCY: 124ms | PEERS: 00 | BUFFER: 100%     │
└─────────────────────────────────────────────────────────────┘

1. Concrete Diagnostic Codes

Rather than vague error toasts, the footer bar reports exact HTTP status codes, edge worker response times, and round-trip ping deltas:

export interface SystemHealthState {
  networkStatus: "ONLINE" | "DEGRADED" | "UPSTREAM_DOWN" | "RATE_LIMITED";
  lastSuccessfulSyncUtc: number;
  httpStatusCode: number | null;
  roundTripLatencyMs: number;
  retryCountdownSec: number;
}
 
export function formatStatusBar(state: SystemHealthState): string {
  switch (state.networkStatus) {
    case "ONLINE":
      return `NET: OK | RTT: ${state.roundTripLatencyMs}ms | SYNC: ${formatUtcTime(state.lastSuccessfulSyncUtc)}`;
    case "DEGRADED":
      return `NET: HIGH_LATENCY (${state.roundTripLatencyMs}ms) | HOLDING_STATE`;
    case "UPSTREAM_DOWN":
      return `NET: UPSTREAM_ERR (${state.httpStatusCode || 502}) | RETRY IN ${state.retryCountdownSec}s`;
    case "RATE_LIMITED":
      return `NET: RATE_EXCEEDED (429) | BACKING OFF ${state.retryCountdownSec}s`;
  }
}

2. Preserving Context During Partitions

When an internet partition occurs, Hushwire does not erase the canvas or replace the radar grid with an error illustration. The existing contacts transition into CARRIER_LOST state, their positions remain anchored, and the timestamp of the last valid fix remains prominently displayed. The observer retains full historical context while the network recovers.

Resisting Premature Feature Bloat

During the initial public development cycle, external feature requests poured in rapidly:

• “Can you add 3D satellite terrain flythroughs like Google Earth?”
• “Can you integrate machine learning to predict flight arrival delays?”
• “Can you add SMS notifications when flights pass over my house?”
• “Can you build a social feed where users can upvote interesting planes?”

Every one of these features represents a significant distraction from our core mission. Adding 3D terrain rendering requires megabytes of WebGL textures, dragging mobile GPUs to a crawl. Delay prediction requires heavy machine learning dependencies and cloud data pipelines. Social mechanics turn a quiet background tool into an attention-seeking feed.

Feature Proposal	Decision	Architectural Rationale
3D Terrain Flythroughs	❌ Rejected	Increases bundle by 8 MB; breaks 24-hour memory stability.
Social Feeds / Upvotes	❌ Rejected	Destroys ambient calmness; creates attention-seeking friction.
Push Notification Alerts	❌ Rejected	Encourages phone checking; contradicts quiet observatory design.
100 NM Bounded Radar Scope	✅ Maintained	Preserves sub-35 MB memory footprint and zero CPU idle drain.
Zero-Retention Ephemeral URLs	✅ Maintained	Eliminates database risk and preserves user data sovereignty.

Saying “no” to complexity is the primary responsibility of software engineering. By constraining Hushwire to a single, focused task—rendering local airspace with calm clarity—the codebase remains maintainable, auditable, and resilient.

Open Development and Verification

The road to Beta 0.1 was shaped by community testing and reproducible bug reports. Community members running secondary displays across varied platforms (macOS, Linux on Raspberry Pi, Windows touch kiosks) helped identify subtle rendering edge cases:

1. Sub-pixel line jitter on fractional DPI displays: Resolved by snapping canvas coordinate transforms to integer physical device pixels (Math.round(val * window.devicePixelRatio)).
2. WebSocket connection stalling behind corporate proxies: Mitigated by implementing graceful fallback to HTTP/2 same-origin polling at 4-second intervals.
3. Memory fragmentation over 48-hour continuous runs: Solved by replacing dynamic object allocations with static TypedArray ring buffers.

The Engineering Ethos Ahead

Hushwire does not claim to replace professional air traffic control consoles or multi-million-dollar aviation operations suites. It is a modest, independent software project exploring how personal knowledge management and physical computing intersect with ambient visualization.

As we move toward Beta 0.2 and the modular multi-band ingest chassis, our development principles remain unchanged:

• Quiet competence over flashy demonstrations.
• Grounded realism over unverified claims.
• Respect for user attention, device resources, and data privacy.

The code remains open, the failures remain visible, and the skies above remain open for honest observation.

---

• Directus Target: hushwire
• Garden Source Reference: Hushwire Roadmap, Launch Retrospectives, MOC - Fleet Operations, MOC - Bosun PKM Tools