Backend architecture

backend/
├── main.py                     # FastAPI app, middleware, API routes
├── ais_proxy.js                # Node.js WebSocket proxy for aisstream.io
├── carrier_cache.json          # Persisted carrier OSINT positions
├── cctv.db                     # SQLite CCTV camera database
├── config/
│   └── news_feeds.json         # User-customizable RSS feed list
└── services/
    ├── data_fetcher.py         # Scheduler + fetcher orchestration
    ├── ais_stream.py           # AIS WebSocket client
    ├── carrier_tracker.py      # OSINT carrier position tracker
    ├── cctv_pipeline.py        # Multi-source CCTV ingestion
    ├── geopolitics.py          # GDELT + Ukraine frontline
    ├── region_dossier.py       # Right-click country/city intelligence
    ├── sentinel_search.py      # Sentinel-2 STAC imagery search
    ├── radio_intercept.py      # Scanner radio feed integration
    ├── kiwisdr_fetcher.py      # KiwiSDR receiver scraper
    ├── schemas.py              # Pydantic response models
    ├── network_utils.py        # HTTP client with curl fallback
    ├── api_settings.py         # API key management
    └── news_feed_config.py     # RSS feed config manager

@asynccontextmanager
async def lifespan(app: FastAPI):
    from services.env_check import validate_env
    validate_env(strict=True)

    # 1. Load AIS disk cache, open WebSocket
    start_ais_stream()

    # 2. Start OSINT carrier position tracker
    start_carrier_tracker()

    # 3. Register APScheduler jobs (fast=60s, slow=5min)
    start_scheduler()

    # 4. Full preload in background — server accepts requests immediately
    def _background_preload():
        update_all_data()

    threading.Thread(target=_background_preload, daemon=True).start()

    yield  # server runs here

    stop_ais_stream()
    stop_scheduler()
    stop_carrier_tracker()

def update_fast_data():
    """Fast-tier: moving entities — every 60s."""
    fast_funcs = [
        fetch_flights,
        fetch_military_flights,
        fetch_ships,
        fetch_satellites,
    ]
    with concurrent.futures.ThreadPoolExecutor(max_workers=len(fast_funcs)) as executor:
        futures = [executor.submit(func) for func in fast_funcs]
        concurrent.futures.wait(futures)

def update_slow_data():
    """Slow-tier: contextual data — every 5 minutes."""
    slow_funcs = [
        fetch_news, fetch_earthquakes, fetch_firms_fires,
        fetch_defense_stocks, fetch_oil_prices, fetch_weather,
        fetch_space_weather, fetch_internet_outages,
        fetch_cctv, fetch_kiwisdr, fetch_frontlines,
        fetch_gdelt, fetch_datacenters, fetch_military_bases, fetch_power_plants,
    ]
    with concurrent.futures.ThreadPoolExecutor(max_workers=len(slow_funcs)) as executor:
        ...

_ADMIN_KEY = os.environ.get("ADMIN_KEY", "")

def require_admin(request: Request):
    if not _ADMIN_KEY:
        return  # No key set — allow all (local dev)
    if request.headers.get("X-Admin-Key") != _ADMIN_KEY:
        raise HTTPException(status_code=403, detail="Forbidden — invalid or missing admin key")

limiter = Limiter(key_func=get_remote_address)

@app.get("/api/live-data/fast")
@limiter.limit("120/minute")
async def live_data_fast(request: Request, ...):
    ...

def _etag_response(request: Request, payload: dict, prefix: str = ""):
    content = json.dumps(payload)
    etag = hashlib.md5(f"{prefix}{content}".encode()).hexdigest()[:16]
    if request.headers.get("if-none-match") == etag:
        return Response(status_code=304,
                        headers={"ETag": etag, "Cache-Control": "no-cache"})
    return Response(content=content, media_type="application/json",
                    headers={"ETag": etag, "Cache-Control": "no-cache"})

from fastapi.middleware.gzip import GZipMiddleware
app.add_middleware(GZipMiddleware, minimum_size=1000)

_SECRET_VARS = [
    "AIS_API_KEY", "OPENSKY_CLIENT_ID", "OPENSKY_CLIENT_SECRET",
    "LTA_ACCOUNT_KEY", "CORS_ORIGINS", "ADMIN_KEY",
]

for _var in _SECRET_VARS:
    _file_var = f"{_var}_FILE"
    _file_path = os.environ.get(_file_var)
    if _file_path:
        with open(_file_path, "r") as _f:
            os.environ[_var] = _f.read().strip()

class HealthResponse(BaseModel):
    status: str
    last_updated: Optional[str]
    sources: Dict[str, int]   # feature counts per layer
    freshness: Dict[str, str] # ISO timestamps per source
    uptime_seconds: int

class RefreshResponse(BaseModel):
    status: str

class RouteResponse(BaseModel):
    orig_loc: Optional[list]
    dest_loc: Optional[list]
    origin_name: Optional[str]
    dest_name: Optional[str]