01 / The question
Can the library hold up
outside its own example?
A reusable tool needs somewhere to prove itself. A small reference example can explain an interface, but it does not show how the parts fit together in an application with its own rules, data, and deployment.
Lontra Creek gives StreamOtter that separate setting: a fictional river-otter study with gauge stations, tagged otters, camera traps, and protected den sites. The world is made up. The data delivery path is working software, with a production stack that includes real Kafka.
02 / The decisions
Give the world rules
worth paying attention to.
I made the simulation deterministic: the same seed and study tick produce the same world. It checkpoints as JSON, allowing a restarted field station to recompute where it left off. That makes the demonstration repeatable and gives debugging a stable reference.
The details have consequences. Storm runoff travels downstream, so gauges see a crest at different times. Otters follow daily activity patterns and shelter from high water. When an otter is in its den, its public channel withholds its location. The application decides what should be public before that information reaches a browser.
03 / What I built
From watershed
to field station.
The project separates the simulation, the field-station application, the public site, and deployment configuration. The field station supplies StreamOtter configuration and handlers, sessions, a site API, and the simulation runner that publishes to Kafka.
The application consumes an exact version of the published StreamOtter npm package. It does not depend on a special checkout of the library. Local development replays the simulation through the gateway without Kafka; the production container stack uses Kafka, the gateway, the field station, and Caddy. That distinction is explicit in the development instructions.
04 / The proof
Test the whole path.
The repository documents a full-stack check on every pull request. It brings up the container stack with temporary secrets and exercises it from outside, including Kafka connections over TLS with SCRAM authentication. That is evidence about the integrated deployment, beyond the simulation alone.
The home page with its live panel and the guided field station are hosted at StreamOtter.dev. Their purpose is to let the library’s promises become observable application behavior. StreamOtter’s case study explains the reusable delivery model; this project shows the work of building a separate application around it.
05 / A second consumer
The creek becomes
a game.
Pup Patrol is a separate React app built around the same fictional world. It reads public den, camera, and creek-overview views through StreamOtter’s React hooks, turning field updates into a short otter-herding game.
The game is a local build, with a public launch planned for lontracreek.com. Its case study covers the game engine, canvas rendering, and visible treatment of stale or recorded data.
Read the game case study ↗06 / Where it stands
A live place
to inspect the promises.
StreamOtter.dev is public. The home page displays changing gauge readings and otter activity, and the field station guides visitors through the lifecycle of a subscription. The site also provides a playground, a workbench tour, and documentation for developers inspecting the toolkit.
The creek, its otters, and its weather are simulated. The Kafka pipeline, gateway, and browser subscriptions are real. The underlying package remains a release candidate; a hosted demonstration gives those guarantees a place to be explored without implying a stable API.
Jason Fricano