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 field station run locally. 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 / Where it stands
Working locally.
More to make public.
The production stack is proven in CI according to the project’s current delivery record, but the demonstration is not yet hosted. The remaining pages, hosted demo, and Failure Lab are in progress. There is no public live station to visit from this portfolio yet.
A guided failure scenario will make interrupted delivery easier to inspect, but it is not presented here as a finished feature. For now, the source and setup instructions are the available evidence. Fictional otters should not come with fictional release claims.
Jason Fricano