Expand README with architecture, surfaces, and ranking details

[jehanazad]

Summary

Comprehensive documentation update to the README that clarifies the system architecture, documents all user-facing surfaces, expands the quick-start guide, and provides detailed information about the Tower Finder API and ranking algorithm.

Key Changes

• Clarified system scope: Updated introduction to explain that RETINA is a multi-surface system (testmap, map, dashboard, Tower Finder) served by a single FastAPI backend
• Added Surfaces table: New section documenting the four distinct user-facing surfaces with their purposes
• Expanded repo layout: Reorganized and detailed the project structure, including new directories (deploy/, docs/) and all git submodules with descriptions
• Enhanced quick-start guide:
  • Updated backend setup to install all library dependencies (custody, simulation, analytics)
  • Added RETINA_ENV=dev auth bypass explanation
  • Clarified frontend development with hostname-based surface selection
  • Added reference to ONBOARDING.md for tests and deployment
• Documented Tower Finder API comprehensively:
  • Added new parameters: radius_km, frequencies, updated limit and source defaults
  • Expanded response schema with new fields: antenna_height_m, frequency_matched, elevation_m, altitude_m
  • Added explanation of elevation API behavior
  • Documented additional endpoints: /api/elevation, /api/health, /api/config
• Detailed ranking algorithm: Expanded "How Ranking Works" section with 8-step process including band filtering, EIRP estimation, sensitivity floor, distance classification, deduplication, and ranking criteria
• Added configuration note: Explained that all ranking thresholds are configurable via tower_config.json and runtime API
• Expanded tech stack: Added specific versions, libraries (numpy/scipy, fastapi-users, pyarrow, boto3), and data sources (FCC TV/FM Query, Open-Meteo)
• Added navigation: New "Where to go next" section with links to detailed documentation files

Notable Details

• Clarified that RETINA_ENV=dev enables auth bypass for local development without OAuth setup
• Explained hostname-based surface routing (localhost → tower search, testmap.localhost → live map)
• Documented the elevation API fallback behavior and null handling
• Provided concrete examples of ranking logic (distance classes, band preferences, frequency matching)
• Emphasized that configuration is runtime-editable through both API and dashboard

https://claude.ai/code/session_011uKX1ha2J7S3Err5ZWtJBY

[claude]

Claude finished @jehanazad's task in 2m 55s —— View job

---

Reviewing PR #135

• Gather context (PR diff, repo structure)
• Verify documentation claims against actual code
• Check Tower Finder API docs against implementation
• Check ranking algorithm docs against implementation
• Post final review

This is a docs-only change (README.md, +120/-48), so I cross-checked every factual claim against the actual code rather than just reading prose. It holds up very well — this is unusually accurate documentation.

Verified correct:

• Repo layout (deploy/, docs/, all 5 libs/ submodules) matches what's on disk.
• RETINA_ENV=dev auth bypass: confirmed in backend/core/users.py:47 (AUTH_BYPASS = not AUTH_ENABLED and _RETINA_ENV in ("dev", "test", "staging")), and it does map to an admin identity (ANONYMOUS_USER has "role": "admin", "is_superuser": True at backend/core/users.py:216-225).
• /api/towers params in backend/routes/towers.py:78-100: radius_km (0–300, 0→default), limit (0–200, 0→default), source default auto with lat/lon-based detection, frequencies (max 10, parsed in tower_ranking.py:232) — all match the table exactly.
• Shipped defaults quoted in the README (radius_km default 80, limit default 100, sensitivity floor −120 dBm, 6 dBi rx gain, band ranges, distance classes) match backend/config/tower_config.json byte-for-byte.
• Ranking algorithm steps (band filter → EIRP estimate/fallback 50/60 dBm → FSPL + gain → sensitivity discard → distance classify → dedup by callsign+frequency → sort by freq-match → band → distance-class → power) match backend/services/tower_ranking.py:252-364 step for step, including the exact sort priority order.
• elevation_m/altitude_m null-on-failure behavior, /api/elevation, /api/health (?strict=1), /api/config GET (public) vs PUT (admin-only) all match backend/routes/towers.py.
• Tech stack versions (Python 3.12 via target-version = "py312", fastapi-users+SQLite, pyarrow, boto3, numpy/scipy) match backend/requirements.txt and pyproject.toml.
• Hostname-based surface routing (localhost → tower search, testmap.localhost → live map) matches frontend/src/utils/domains.ts and App.tsx:71.
• TCP port 3012 confirmed in backend/main.py:77.

One minor nit: the example response JSON (README.md:104-140) isn't internally self-consistent with the documented formula. Given eirp_dbm: 79.1, distance_km: 12.4, frequency_mhz: 177.5, and 6 dBi rx gain, received_power_dbm should compute to ≈ −14.2 dBm (FSPL ≈ 99.3 dB), not the −21.3 dBm shown. Not a functional issue since it's just illustrative text, but worth regenerating the example from a real API call so the numbers check out for anyone trying to verify the math by hand.

Everything else — surfaces table, quick-start steps, config-editability note, "Where to go next" links — checks out against the current codebase. Nice work.