Skip to content

For developers

This section is for people who want to run backscatter from source, understand how it works, or contribute. If you just want to use it, you want the Get started guides instead — no need to come here.

What backscatter is (the honest pitch)

backscatter is a small, readable Python app with a vanilla-JS frontend. No magic, no lock-in:

  • It runs anywhere. A normal Python 3.12 environment, or one Docker container. No cloud account, no managed services.
  • Any US location. The active radar is derived from a configured lat/lon against a bundled NEXRAD site table — nothing is hardcoded to one place.
  • All free public data. Radar comes straight from NOAA's open S3 buckets, accessed anonymously. No API keys, no paid feeds, no credit card — and that's a hard rule, not a coincidence.
  • Yours to change. MIT licensed. Fork it, run it, modify it.

The shape of it

ingest  →  decode  →  render  →  store  →  api  →  web
(S3)       (Py-ART)   (reproj +   (SQLite   (Fast   (MapLibre
                       colormap)   + files)  API)    map)

A background collect loop walks that pipeline on an interval; the api serves the saved frames to the browser. The How it fits together page draws this out properly.

Where to go next

  • Run it locally

    Clone to a running app in a couple of minutes (the fast uv path, no Docker).

    Run it locally

  • How it fits together

    The pipeline, module by module, with a diagram.

    Architecture

  • Running the tests

    pytest, ruff, mypy, and the frontend test.

    Testing

  • Contributing

    How changes are made here — slices, ADRs, and the one rule about rendering.

    Contributing

You can also read the Roadmap (the slice-by-slice build history) and the Design decisions (ADRs) to see why things are the way they are.