Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ flowchart TB
end

subgraph central["Central server — cloud droplet"]
tf["Tower-Finder = the RETINA server<br/>FastAPI: TCP ingest + tracker + geolocator + analytics<br/>nginx + live-map SPA + admin dashboard"]
tf["retina-server = the RETINA server<br/>FastAPI: TCP ingest + tracker + geolocator + analytics<br/>nginx + live-map SPA + admin dashboard"]
tfs[tower-finder-service · site-survey utility]
end

Expand All @@ -53,7 +53,7 @@ flowchart TB
- **Edge radar node** — a Raspberry Pi 5 running `owl-os` with the `retina-node`
Docker Compose stack. Captures IQ from an SDR (SDRplay RSPduo), computes
delay-Doppler detections, and forwards them to the central server.
- **Central server** — the `Tower-Finder` monorepo (the repo name is historical;
- **Central server** — the `retina-server` monorepo (the repo name is historical;
it is now the full RETINA server). Ingests detections from all nodes, runs
multi-target tracking and multi-node geolocation, and serves the live maps.
- **Web clients** — the live map (`map.retina.fm`) and admin dashboard
Expand All @@ -74,7 +74,7 @@ flowchart LR
a2d -->|truth| api
api -->|detections over TCP · config-gated| trk

subgraph central["inside Tower-Finder — in-process libraries"]
subgraph central["inside retina-server — in-process libraries"]
trk[tracker · Kalman + GNN] --> geo[geolocator · Levenberg-Marquardt, multi-node]
geo --> state[in-memory track state]
end
Expand Down Expand Up @@ -133,7 +133,7 @@ JSONL output is the offline/batch path, not the live feed.
`owl-os` (systemd, `:80`, `owl.local`). Management plane, not data plane.

### Central server
- **Tower-Finder** (Python FastAPI + React/Vite SPAs) — the RETINA central server.
- **retina-server** (Python FastAPI + React/Vite SPAs) — the RETINA central server.
One container (nginx + uvicorn) hosting: TCP detection ingest (`:3012`), the
multi-target **tracker** (Kalman + GNN) and node associator, the multi-node
**geolocator** (Levenberg-Marquardt), auth/admin/analytics, the live-map SPA,
Expand Down Expand Up @@ -207,7 +207,7 @@ JSONL output is the offline/batch path, not the live feed.
Switching the *data-plane* network is automated; switching the *OTA control*
plane is intentionally manual.

**Central / cloud:** the `Tower-Finder` monorepo container + `tower-finder-service`
**Central / cloud:** the `retina-server` monorepo container + `tower-finder-service`
run on a DigitalOcean droplet, joined by a shared `retina-edge` Docker network and
fronted by Cloudflare; both deploy via `git reset --hard origin/main` +
`docker compose up -d --build` from GitHub Actions on push to `main`. The public
Expand Down Expand Up @@ -238,7 +238,7 @@ authoritative inventory — deployment topology changes faster than this table.
| `tar1090-node` | ADS-B decode + map + proxy | readsb, nginx, Node |
| `retina-spectrum` | Illuminator spectrum survey | C++ |
| `retina-gui` | Node management UI | Python/Flask |
| `Tower-Finder` | Central RETINA server (ingest, track, geolocate, maps) | Python/FastAPI, React/Vite |
| `retina-server` | Central RETINA server (ingest, track, geolocate, maps) | Python/FastAPI, React/Vite |
| `tower-finder-service` | Illuminator site-survey microservice | Python/FastAPI |
| `retina-tracker` | Multi-target tracker (Kalman/GNN) — library vendored into central server | Python |
| `retina-geolocator` | LM delay/Doppler → position solver — library vendored into central server | Python |
Expand Down Expand Up @@ -271,7 +271,7 @@ flowchart LR
spec[retina-spectrum]
gui[retina-gui]
end
subgraph central["Central server — Tower-Finder (libs in-process)"]
subgraph central["Central server — retina-server (libs in-process)"]
trk[retina-tracker] --> geo[retina-geolocator] --> ana[retina-analytics]
end
sim[retina-simulation]
Expand Down Expand Up @@ -302,7 +302,7 @@ flowchart LR
os[owl-os] -->|sysdeps + bundles| gui[retina-gui]
os -->|SDRplay API + watchdog| blah
blah <-->|shared SDRplay libs · RSPduo exclusive| spec
tf[Tower-Finder] -.->|vendors as git submodules| libs["retina-tracker / -geolocator /<br/>-analytics / -custody / -simulation"]
tf[retina-server] -.->|vendors as git submodules| libs["retina-tracker / -geolocator /<br/>-analytics / -custody / -simulation"]
```

<details>
Expand All @@ -317,7 +317,7 @@ git submodule and imported in-process. **HTTP** = REST/proxy.
| **retina-node** | compose | compose | compose | compose (excl.) | – | – | – | URL env |
| **blah2-arm** | – | HTTP `/api/dd` | – | HW libs | Format (forward¹) | – | – | – |
| **retina-gui** | HTTP :49152 | – | HTTP :8078 | SSE proxy :3020 | – | – | – | HTTP `/api/towers` |
| **Tower-Finder** | bridge (radar3) | Format | – | – | lib (in-process²) | lib (in-process²) | lib | dup logic |
| **retina-server** | bridge (radar3) | Format | – | – | lib (in-process²) | lib (in-process²) | lib | dup logic |
| **retina-tracker** | Format (in) | Format (adsb) | – | – | – | Format (out) | – | – |
| **retina-geolocator** | reads config.yml | – | – | – | Format (in) | – | Format (out) | – |
| **retina-simulation** | – | – | – | – | Format→:3012 | – | – | towers API |
Expand Down
4 changes: 2 additions & 2 deletions docs/brand/brand-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ stylesheet with the others:

- **offworldlabs.com** ([`landing-page-owl`](https://github.com/offworldlabs/landing-page-owl)) — the lab
- **retina.fm** ([`landing-page-retina`](https://github.com/offworldlabs/landing-page-retina)) — the product
- **dash.retina.fm** (`Tower-Finder/dashboard`) — the admin console
- **map.retina.fm** (`Tower-Finder/frontend`) — the live radar map
- **dash.retina.fm** (`retina-server/dashboard`) — the admin console
- **map.retina.fm** (`retina-server/frontend`) — the live radar map

They read as one family, but each has its own voice. The map is the odd one out:
it is the only dark surface, a Flightradar24-style operational console.
Expand Down
2 changes: 1 addition & 1 deletion docs/contracts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ than in either repository, so neither owns it and both can diff it.
## `nodes_api_v1.yml`

The node ↔ server wire contract, currently **1.1.1**. Three independent implementations depend on
it: the server in `Tower-Finder`, the node client in `retina-node`, and the conformance harness.
it: the server in `retina-server`, the node client in `retina-node`, and the conformance harness.

**It is versioned, not frozen.** The changelog at the top of the file is authoritative. A change is
a coordinated event rather than a silent edit: bump the version, record the change in the changelog,
Expand Down
8 changes: 4 additions & 4 deletions docs/cross-cutting-changes.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ this with the connection matrix in [`architecture.md`](./architecture.md) §6.
This is the highest-blast-radius contract in the system.

- **Tower ranking logic:** **duplicated** in
`Tower-Finder/backend/.../tower_ranking.py` and
`retina-server/backend/.../tower_ranking.py` and
`tower-finder-service/backend/tower_ranking.py` — edit both until deduplicated.
**retina-spectrum** and **retina-gui** are downstream HTTP consumers of `/api/towers`.

Expand All @@ -30,13 +30,13 @@ this with the connection matrix in [`architecture.md`](./architecture.md) §6.

- **Tracker / geolocator / analytics algorithms:** the libraries **retina-tracker** /
**retina-geolocator** / **retina-analytics** are vendored as git submodules in
**Tower-Finder** and run in-process. A change means bumping the submodule in
Tower-Finder and redeploying the central server (not a separate tracker service).
**retina-server** and run in-process. A change means bumping the submodule in
retina-server and redeploying the central server (not a separate tracker service).

- **OTA / fleet onboarding flow:** spans **owl-os** (Mender inventory scripts) →
**node-infra** (auto-accept + deploy) → **retina-gui** (`wizard_pending` gate) →
**retina-node** (Mender artifact). All four participate.

- **The `retina-edge` Docker network / `*.retina.fm` deployment:** shared by
**tower-finder-service** and the Tower-Finder-hosted nginx vhost on the central
**tower-finder-service** and the retina-server-hosted nginx vhost on the central
droplet. See [`architecture.md`](./architecture.md) §4 for the live-endpoint table.
Loading