Feed Catalog

The feed adapter serves the Farsight catalog as a portable sidecar for map clients. It exposes static datasets, live upstream snapshots, RSS metadata, and normalized GeoJSON over HTTP and gRPC.

Are The Feeds Airgapped Or Live?

It is case by case.

• Static datasets are airgapped at runtime. They are baked into datasets/*.json and served without calling the network.
• Built-in upstreams are live when ENABLED_UPSTREAMS includes them. The adapter polls those providers and prefers the fresh snapshot for that layer.
• Service feeds are live through the Farsight adapter's API routes, each of which polls a real external upstream (see the Feed Reference). Some routes read preseeded Redis/bootstrap state, a few serve static local files, and the rest are adapter-derived from other feeds.
• RSS feeds are live through the RSS proxy/aggregator and constrained by the allowed-domain catalog.

The generated Feed Reference page documents every current dataset, upstream source, and service feed with a runtime mode.

Local Stack

docker compose up -d --build feed-adapter

TrailBase is exposed on http://localhost:4001; the adapter is exposed on http://localhost:18080 and http://localhost:50051.

The adapter HTTP port also serves:

• /docs for this documentation
• /reference for the Scalar API reference
• /farsight for the GeoJSON map console
• /openapi.json and /openapi.yaml for the API contract

For sidecar hot loading during development, run the compose overlay:

docker compose -f compose.yaml -f compose.dev.yaml up -d --build feed-adapter

The overlay bind-mounts adapter/static/farsight/*, adapter/openapi.yaml, and the built Fumadocs .next artifacts into the container. Rebuild the docs with npm run build after MDX/layout changes, then refresh /docs.

Source Of Truth

• ../feeds-catalog.yaml defines layers, datasets, upstreams, refresh intervals, and adapter routes.
• ../services/services.yaml defines app service feeds and their API endpoints.
• ../compose.yaml wires trailbase, feed-adapter, and the example map app.