Skip to content

Technical Decisions

This page is an ADR-lite, short opinionated notes on the load-bearing choices that shape the codebase. Each entry follows the same shape: Decision, Context, Rationale, Trade-offs.

Vertical domain slices

Decision. The backend is organized as vertical slices under backend/internal/services/<domain>/. Each slice owns its full stack in one package: store.go (persistence), service.go (business logic), handler.go (HTTP), routes.go (route mounting), plus wire.go/deps.go and colocated *_test.go. Multi-aggregate domains prefix files and types by aggregate (event_service.go / EventService). Constructors are New<Thing>; the object graph is composed in backend/internal/wiring. See Domains.

Context. A feature (events, chat, plans) touches persistence, business rules, and an HTTP surface together. Grouping code by technical layer spreads one feature across four sibling trees, so a single change fans out and the blast radius of a package is unclear.

Rationale. A slice is the unit of ownership: everything a feature needs sits in one directory, and the package boundary is the domain boundary. Response shapes live in the slice that serves them, so small cross-cutting briefs (UserBrief, EventBrief) are duplicated per domain rather than shared through a central package. Cross-domain needs are expressed as narrow interfaces (ports) declared in the consumer's deps.go and implemented by the provider, which keeps import edges one-way and mockable.

Trade-offs. A little duplication (the briefs) in exchange for decoupled packages. Genuinely shared types still live in backend/internal/models; the discipline is to not promote a type there just because two slices reference it.

Wire for dependency injection

Decision. Use Google's Wire to assemble the backend's object graph at compile time. The provider set lives in backend/internal/wiring/providers.go; InitializeApp is generated and called once from main.go.

Context. A typical request touches a handler, a service, one or more repositories, the Redis client, the WebSocket Hub, the Asynq client, and configuration. Hand-wiring this in main becomes unreadable; a runtime container hides errors until startup.

Rationale. Wire validates the entire graph at go generate time. Missing or ambiguous dependencies surface as compile errors, with zero runtime overhead. The output is plain Go that a human can read.

Trade-offs. Requires running go generate after provider changes. The generated file is committed and reviewed like any other code. Constructor signatures become the public contract — refactors ripple, which is by design.

sqlc + pgx + Postgres + PostGIS

Decision. Persist all durable state in a single PostGIS-enabled Postgres database, accessed through sqlc-generated, type-safe queries over pgx/v5 behind a per-domain Store (the persistence layer of each vertical slice under backend/internal/services/<domain>/). There is no ORM. Each domain's generated query code lives in backend/internal/services/<domain>/<domain>db/, and the Store is the only layer that runs it, mapping pgx rows to *models.X via internal/database/pgconv. The schema is defined by goose migrations in backend/db/migrations/; backend/db/schema/ is a generated per-domain snapshot that sqlc targets.

Context. The product is geospatial (events, moments, locations) and relational (users, friendships, participants). A single ACID store keeps reasoning simple while leaving room to scale reads. Queries need to be fast on the hot paths and hard to get wrong at the type level.

Rationale. PostGIS handles point geometry and proximity queries natively. sqlc compiles hand-written SQL into type-safe Go at codegen time, so column and parameter mismatches are compile errors rather than runtime surprises, with none of the reflection overhead of an ORM query path. pgx/v5 is the driver. Goose migrations are the schema source of truth and run at boot; db.Migrate (which wraps goose ApplySchema plus idempotent RunManual post-steps) keeps a fresh database current. The per-domain Store keeps service and handler code free of pgtype and SQL, returning plain *models.X structs.

Trade-offs. Schema changes are a multi-step flow: write the goose migration, regenerate the db/schema snapshot, edit the domain's queries.sql, and regenerate the <domain>db package, all committed together with a drift guard in CI. In exchange, the query layer is type-checked end to end and free of ORM reflection cost. Logic is concentrated in services rather than the database, so there are no triggers carrying business meaning. Raw SQL is limited to a few PostGIS queries, since pgx cannot decode the geometry column: the Store reads scalar lat/lng and writes geometry via ST_SetSRID(ST_MakePoint(...)).

Asynq for background work

Decision. Use Asynq on Redis for all background processing. Three queues — critical (6), default (3), low (1) — are configured in backend/internal/async/server.go.

Context. Email sends, webhook fan-out, cleanup sweeps, status transitions, and notification dispatch must not block HTTP handlers, and must survive process restart.

Rationale. Asynq gives us retries with exponential backoff, dead-letter queues, weighted priorities, scheduled jobs, and a usable web UI — all on top of Redis we already operate. The scheduler (backend/internal/async/scheduler.go) enqueues recurring jobs (status updates every 5 min, message expiry every 30 s, daily purges, etc.) so the worker is the single execution point.

Trade-offs. Couples background processing to Redis availability. Tasks must be idempotent — Asynq guarantees at-least-once. Stateful long-running work (>~30 s) belongs elsewhere; Asynq is for short, retryable units.

WebSocket Hub with Redis pub/sub fanout

Decision. Each pod runs two in-process WebSocket hubs: SessionHub (per-chat map[roomID]→Room) and ClientHub (per-user connections), each with a Redis-backed PSUBSCRIBE (session:* and client:*) for cross-pod fanout. Both live in the platform/ws bundle (backend/internal/platform/ws/session_hub.go, client_hub.go).

Context. Chat in Tomoda is per-room: each chat has a single room, and the cardinality of concurrent rooms is moderate. The per-user ClientHub carries notifications, presence, and multi-device sync on its own channel. The backend runs with multiple replicas (see Horizontal scaling).

Rationale. Each WS connection terminates at the pod it dialled, so some per-pod state is unavoidable. Redis pub/sub is the cheapest way to bridge those pods: one PUBLISH per broadcast, one PSUBSCRIBE per pod, no ingress session affinity, no separate broker to operate. An origin pod-ID tag in the wire envelope drops the echo that would otherwise round-trip back to the sender.

Trade-offs. Best-effort delivery (at-most-once) across pods — Redis pub/sub doesn't persist or retry. We accept this because every chat message is also persisted via ChatService.SendMessage, so a missed pub/sub frame is recoverable on reconnect. Every pod's subscriber receives every event's traffic (one cheap channel-name match per inbound message); if a single Redis instance ever becomes the bottleneck, the next step is to shard the channel namespace, not change the data model. See Real-time.

Single image, multiple modes

Decision. Build one backend image. Select what to start at runtime via --mode (or SERVER_MODE env): full, multi-hub, api-hub, ws-hub, or async. See backend/cmd/server/main.go.

Context. Once horizontal scaling was on the table we needed separate scaling profiles for the API surface (CPU/RPS) and the async worker pool (queue depth) — and didn't want to maintain two Dockerfiles or two CI pipelines for it.

Rationale. Modes are cheap: one flag, a few booleans, a handful of if guards around Hub.Run, WorkerServer.Start, SchedulerManager.Start, and route registration. /health and /ready are always served so k8s probes work in every mode, including async.

Trade-offs. The Wire-built dependency graph is still wired in full on every startup — unused components are constructed but never started. This costs a few hundred milliseconds of init and a slightly larger heap, in exchange for not splitting the binary or DI graph along mode lines. The reserved modes (api-hub, ws-hub) are ready to split WS into its own pod without a code change when the deployment warrants it.

PostGIS-only spatial indexing (H3 retired)

Decision. Spatial dedup and viewport clustering run entirely on the PostGIS geography indexes; the shared Spatial mixin adds denormalized lat/lng float columns for reads that don't need PostGIS. No H3 cell columns exist.

Context. Earlier revisions stored an Uber H3 cell per Location (resolution 12, ~5 m) for dedup, and a map prototype added coarser r6/r8 parent cells for cell-keyed clustering endpoints. The frontend map settled on bbox viewport queries (/discovery/map), so the cell-keyed endpoints never gained a client and the columns had no readers.

Rationale. With no reader, the H3 columns were write-only cost: a cgo dependency (h3-go), extra indexes to keep aligned with the geometry, and a second spatial vocabulary beside PostGIS. ST_DWithin on the GiST geography indexes already serves dedup ("is this lat/lng near an existing place?") with per-category radii, and bbox queries serve clustering at every zoom the app uses.

Trade-offs. Constant-time cell-equality lookups are gone; anything that would have bucketed by fixed-resolution cells now pays a radius or bbox query. If a future surface needs cell bucketing, the columns can be recomputed from the stored geometry.

Photon as Google Places fallback

Decision. Use self-hosted Photon (OSM-backed) as the primary geocoder, with Google Places available as an optional secondary source. The dev stack runs Photon on port 2322 (docker-compose.dev.yml).

Context. Geocoding and autocomplete are hit on nearly every interactive map screen. Google Places is excellent but billed per-request; coverage and quality vary by region.

Rationale. Self-hosting Photon caps the marginal cost at zero and gives us latency control. For users where OSM coverage is thin we still fall through to Google. The split keeps the bill bounded while preserving result quality where it matters.

Trade-offs. Operational ownership — Photon must be deployed, refreshed, and monitored. OSM data updates are not as crisp as Google's commercial dataset for points-of-interest discovery; we accept that on the autocomplete path.

JWT + refresh tokens

Decision. Authenticate stateless requests with a 24-hour JWT (HS256), paired with a server-stored refresh token mirrored into Redis. See Authentication (system view) and Backend → Auth service (implementation).

Context. Clients are mobile-first and need to survive long offline windows. Session lookup on every request would push extra load onto Postgres or Redis at high QPS.

Rationale. A short-lived JWT lets the API authorise from the bearer alone — no per-request DB hit on the happy path. The refresh token gives us revocation: deleting the row + Redis key invalidates the chain on the next refresh. Sessions and login history still live in Postgres for user-facing controls.

Trade-offs. JWTs cannot be invalidated mid-lifetime — a compromised access token is valid until expiry. We mitigate by keeping expiry to 24 h, supporting forced refresh, and offering per-session revocation. The system is more complex than pure server sessions; we have judged the latency win worth it.

Expo Router (file-based, single codebase)

Decision. Ship iOS, Android, and the web from one Expo SDK 55 codebase with Expo Router for navigation. Routes live under frontend/app/.

Context. The product surface is identical across platforms — a small team cannot afford three navigators or three feature implementations.

Rationale. File-based routing matches the way the team mentally groups screens ((moments), (social), auth/, home/, etc.) and removes a class of imperative navigation bugs. React 19 + react-native-web gives us a usable web build of the same screens.

Trade-offs. A few platform-specific concerns (passkey UX, native sign-in flows, map providers) require Platform.OS branching. Some libraries lag Expo SDK releases.

Context + TanStack Query state

Decision. App-wide state uses React Context. Nine providers live in frontend/contexts/ — Auth, Theme, Friends, Location, CreateEvent, PageHeader, Toast, Sheet, MapDock. Server data on hot-path screens uses TanStack Query (@tanstack/react-query). No Redux or Zustand.

Context. Most cross-screen state is small (auth user, current location, ephemeral UI) and fits Context. Screens that share a single data source across multiple tabs (event detail, search results) benefit from TanStack's cache: one fetch, keyed by a *QueryKey factory, shared across every mount.

Rationale. Context keeps the learning curve flat and the data flow easy to grep. TanStack Query is used where its deduplication and staleness model prevents double-fetching across tab mounts. Providers are composed at the root layout (app/_layout.tsx).

Trade-offs. Re-render scope is the developer's responsibility — Contexts are memoised manually with useMemo and useCallback. Not all server data has migrated to TanStack; new screens with cross-tab requirements should use a keyed query hook rather than a hand-rolled useState fetch loop.

Fetch (no axios)

Decision. Use the platform fetch API directly, wrapped in frontend/utils/api.ts (handleResponse) and frontend/services/*.ts thin per-domain wrappers.

Context. Adding axios introduces a non-trivial dependency, a parallel error model, and an interceptor system that ends up duplicating logic that React Native/web already provide.

Rationale. fetch is universal across iOS, Android, and the web. The shared handleResponse centralises the bits we actually need: 401 → session-expired event, JSON parsing, error-message extraction. Token caching lives in frontend/utils/tokenManager.ts.

Trade-offs. No request/response interceptors as a first-class concept — we hand-roll them. No built-in cancellation cookies — we rely on AbortController where it matters.

YAML + env layering

Decision. Backend config is loaded from layered YAML — config.yaml (base) plus config.<env>.yaml (overrides) — with environment variables and GCP Secret Manager filling in secrets via scripts/dev/pull-secrets.sh.

Context. A pure .env approach scales poorly when configuration grows nested (Stripe price IDs, S3 endpoints, WebAuthn RP settings). Mixed-shape config also makes typed loading awkward.

Rationale. YAML expresses nested config naturally and maps cleanly onto the Go config structs in backend/config/config.go. Environment-specific files keep production overrides reviewable. Secrets stay out of files entirely — they are injected at runtime from Secret Manager.

Trade-offs. Two layers (file + env) to mentally merge. Local developers need a config.local.yaml for ergonomics. The split is deliberately worth the clarity at the cost of one additional load path.

One capability registry and authorizer

Decision. Authorization lives in backend/internal/access/. Capabilities are declared once in a registry, roles map to them in one table per surface, a single Authorizer decides from the database, and routes are listed as tables that name the capability they need. Step-up and the private-read reason are properties of a capability, enforced by the one middleware.

Context. Hand-listed gate structs, one middleware per role and per-service step-up calls meant every new route had to remember its own checks, and a forgotten one failed silently.

Rationale. A new capability is a constant, a Def, a role grant and a route entry. A router test fails when a protected route has no capability, a golden role matrix makes permission changes reviewable, and the docs and the client capability list are checked against the registry.

Trade-offs. Every gated request reads the database (one primary-key lookup or one membership join), so permission changes apply immediately and nothing is cached. Routes that need only a signed-in caller still read JWT claims.

URL-scoped partner context

Decision. Partner routes are scoped by URL — /api/v1/partner/:partner_id/... on the backend, /partner/[partner_id]/... on the frontend. There is no "current partner" state in the JWT, the session, or the frontend context.

Context. A user can belong to multiple partners (a personal account that helps run two coffee shops). The system needs to know which partner an action is for, and the answer needs to be auditable in logs.

Rationale. URL-scoping makes every partner-bound action self-describing — the route template names the tenant. Backend middleware reads :partner_id and verifies membership; frontend reads useLocalSearchParams().partner_id from the route. Switching partners is a router navigation, not a state mutation. Audit logs ("who did what to which partner") are trivial because the partner ID is in the request line.

Trade-offs. Routes are slightly longer. A user who belongs to many partners needs the picker (partner/index.tsx) to navigate between them — there's no implicit "stay in the last partner I used" memory. Worth it for the symmetry between client and server, and the absence of stale-state bugs.

Discovery is the read-aggregation domain

Decision. All query and read-aggregation across domains is served by one discovery slice under /discovery: viewport map (/discovery/map), nearby-people radar (/discovery/radar), location detail (/discovery/locations/:id), unified natural-language search (/discovery/search) plus kind-scoped search (/discovery/search/{events,locations,users}), the saved-area pin (/discovery/pin), the taxonomy vocabulary (/discovery/taxonomy, /discovery/taxonomy/resolve), and the full aggregated profile card (/discovery/profiles/:id, optional auth). It queries the DB directly and reuses taxonomy.ParseQuery, the platform/llm semantic resolver, and location geocoding.

Context. Read paths that fan across events, locations, users, and moments do not belong to any single write-owning domain. Scattering them (a find surface, a discovery-map surface, a taxonomy surface, a per-domain profile endpoint) duplicated the geocode-then-rank pipeline and gave the client several vocabularies for one job.

Rationale. A dedicated read domain lets aggregation queries preload and rank across aggregates without threading a write-owner's service. One /discovery prefix is the client's single entry for "what is near here / what matches this query / who is this person", so the intent parser and geocoder are wired once. Write-owning domains stay lean: user serves only the lean card (GET /users/:userId → GetUserCard: {id, name, username, avatar_url, bio, is_friend}), while the full aggregated profile card is a discovery read.

Trade-offs. Discovery reads tables it does not own, so it must track schema changes in several domains. We accept that coupling on the read side because the alternative (an aggregation call graph across five services per map paint) is slower and harder to reason about.

Snapshot event items at plan promotion

Decision. When a plan is promoted to an event, its curated board items are copied into event-owned models.EventItem rows (backend/internal/models/event_item.go), with photos and links frozen as JSONB snapshots. GET /events/:id/items renders that snapshot self-contained; it never reaches back into the plan or item domain.

Context. A plan's board is a live, collaborative, editable canvas. An event's event items are a settled record of what the group agreed to. Rendering the event board by joining live plan items would let a later edit or deletion of the source plan silently rewrite the history of an event that already happened.

Rationale. Copy-at-promotion makes the event board immutable and self-contained: EventItemFromItem snapshots title, body, location, tags, and the photo/link JSON so the card renders without a cross-domain read. Editing the event copy never touches the source plan, and deleting the source plan leaves the event board intact.

Trade-offs. The board is a point-in-time copy: edits made to the plan after promotion do not flow into the event. That is the intended contract (the event is settled), but it means the two can diverge, which is acceptable because the plan and the event are different lifecycle stages.

Self-hosted small LLM behind a generic interface

Decision. The semantic resolution layer (entity-query extraction + place selection for link capture) calls a small quantized LLM over the OpenAI-compatible chat API, behind a generic SemanticResolver interface with an LLMClient transport. Default model is Qwen2.5-3B-Instruct served by Ollama. It is off by default and degrades to the deterministic Serper heuristic when disabled or unreachable.

Context. Serper search adds little value when fed a social caption verbatim: the query is noise and the top result is confidently wrong. The fix needs a model that can distill an entity and judge candidates, but we did not want to add another paid provider or leak captures to a third party.

Rationale. A self-hosted quantized model is compute, not a new vendor, so it satisfies the no-new-provider constraint. Speaking the OpenAI chat shape means self-hosted (Ollama, llama.cpp, vLLM) and most hosted providers are a config swap (base URL, model, key), and a non-compatible provider is a second LLMClient impl behind the same interface, the same pattern as the Photon and Google location adapters. The layer runs in the async enrich worker, so CPU inference is acceptable and a slow or missing model server just falls back.

Trade-offs. Operational ownership of a model server (pull, pin, monitor). A 3B quantized model needs defensive JSON parsing and a confidence gate because it can be unreliable or overconfident; the deterministic G1/G2 guards stay as the floor so the model can only improve on, never replace, the safe path.

Cost-tiered location enrichment

Decision. Every location row gets a cheap backbone (lexical search_text, spatial index, category, Photon localization gap-fill) unconditionally, but the paid tier (Serper /maps, then a budget-capped Google Places call) fires only for rich-detail categories that are not part of the bulk backbone and are not already enriched. isHarvested excludes the density backbone; the daily enrich:upgrade:google budget caps the billed fallback. See Locations.

Context. A planet-scale POI catalog is tens of millions of rows. Paid-enriching all of them, or embedding all of them, costs real money for rows almost no query reaches, while the interactive experience needs rich detail (photos, hours, ratings) on the venues users actually open.

Rationale. Splitting the spend from the backbone means the marginal row costs near zero (self-hosted Photon + Postgres) and the paid budget concentrates on demand-activated, high-value rows. The backbone stays fully findable lexically, spatially, and by category; it just does not carry commercial detail until a category or an engagement earns it.

Trade-offs. A cold backbone row shows sparse detail until someone touches it, and the promotion path (below) adds a write on first meaningful engagement. Both are acceptable: the alternative is an unbounded enrichment bill for coverage users never see.

Demand-driven embeddings via shouldEmbed

Decision. A row carries a semantic vector only when shouldEmbed passes: prominence at or above a floor, curated/promoted provenance, or any engagement. Metadata and signals never qualify a row, and a harvested row never embeds until it is promoted. The cold long tail stays lexical + spatial + category-searchable with no vector. A backbone row a user meaningfully engages with is promoted (harvested → promoted), which clears the enrichment guard and earns it an embedding on demand.

Context. Embedding an entire multi-million-row backbone would need as many vectors and an ANN index over all of them, at real cost, for rows almost no conceptual query reaches.

Rationale. Gating the vector to high-value + engaged rows keeps the embedded set small enough that an in-memory HNSW serves it well, and keeps the embedding-model calls bounded. Lexical recall covers the long tail; only a pure meaning query needs a vector, and those land on the rows that have one.

Trade-offs. A conceptual query cannot reach an un-embedded cold row until it earns a vector. Accepted: those rows are, by definition, the ones no one has engaged and that carry no prominence signal.

Vector search on a leading slice of the embedding

Decision. locations.embedding stores the full 1024-dimension vector; the ANN index is an HNSW over subvector(embedding, 1, 512)::halfvec(512) with cosine distance, and queries order by that same expression with a query vector cut to 512. See Locations.

Context. The embedding model is trained so a leading slice of its output keeps nearly all retrieval quality, and a 512-wide halfvec HNSW is half the size of a 1024-wide one.

Rationale. Storing the full vector keeps the option to search at full width, which then needs only an index rebuild, never a re-embed. Indexing the slice halves index memory with no measured quality loss. It is pgvector-native, no new extension.

Trade-offs. The query must use the exact index expression or the planner falls back to a scan; an integration test pins this with EXPLAIN. If the gated embedded set ever outgrows in-memory HNSW, the next lever is a disk-backed ANN (pgvectorscale / DiskANN), deliberately not adopted now.

go:embed of taxonomy data

Decision. The place/event taxonomy JSON is embedded into the binary with go:embed (backend/data), read through a helper that honors a TAXONOMY_DATA_DIR override but defaults to the embedded copy. A read/parse failure is treated as a real bug and surfaced (fail-loud), not swallowed.

Context. The taxonomy is loaded at boot and from the seeder, which run from different working directories. A relative-path read is fragile across those entrypoints and across container layouts.

Rationale. Embedding makes the data CWD-independent and guarantees it ships with the binary, so boot and the seeder resolve the same vocabulary regardless of where they run. The env override keeps local iteration possible without a rebuild.

Trade-offs. Regenerating the data requires a rebuild to pick up the new embedded copy (or the env override for local testing). Acceptable for data that changes on a monthly-or-slower cadence.

Soft-close instead of hard-delete for closed places

Decision. When a report-outdated refresh concludes a place is permanently closed, the row is tombstoned (is_active=false, business_status=CLOSED_PERMANENTLY, closed_at stamped) rather than deleted. It drops out of forward-facing search but stays fetchable by id. A single provider "not found" never closes a row on its own: not_found_count must cross a threshold, and a later operational refresh reverses the close.

Context. Locations are FK targets for check-ins, moments, events, saves, and passport visits. Deleting a closed place would dangle those references and erase history.

Rationale. A tombstone preserves every FK linkage and keeps deep links resolving with a "permanently closed" label, while excluding the place from search. Corroboration (the not-found counter) plus reversibility guards against false closures from renames, transient provider gaps, and obscure places.

Trade-offs. Closed rows accumulate in the table rather than being reclaimed. Accepted: they are excluded from the hot search paths by is_active, and their history value outweighs the storage.

Set-based load-time city linking

Decision. Each non-city POI's city_id self-FK is assigned in one set-based pass after the whole dataset is loaded, walking the table by primary-key cursor in chunks and running a LATERAL nearest-city KNN join per chunk, rather than resolving the nearest city per row during ingest.

Context. A planet-scale load is tens of millions of POIs. A per-row nearest-city lookup in the ingest loop is tens of millions of round-trips; it also couples city-linking to ingest order (a POI can load before its city).

Rationale. Deferring to one post-load sweep turns the work into a bounded series of index-served UPDATE statements (the KNN order-by rides the GiST coordinate index), runs after every city exists, and is idempotent (only NULL city_id rows are touched), so a re-load leaves linked rows alone. The same city_id then drives per-city highlight promotion and localized-city read assembly.

Trade-offs. City linkage is not available mid-load, only after the sweep. Acceptable: nothing reads city_id until the catalog is fully loaded and promotion runs.

Durable ranking labels + config-driven weights

Decision. Search ranking training labels are persisted to a durable Postgres sink (a sampled ranking_impression carrying each shown candidate's feature vector + every ranking_selection, joined by ranking_query_id), separate from the retention-bound observability logs, and the six rank weights are env-config (RANK_WEIGHT_*) defaulting to the shipped constants rather than compile-time constants.

Context. The offline weight tuner (cmd/rankertune) needs a stable history of what was shown and what users chose; Loki log retention is measured in days. Applying a retuned weight vector as compile-time constants requires a recompile + redeploy.

Rationale. A durable sink gives the retune a growing, joinable label set that survives log retention; writes are best-effort off the hot path (a detached goroutine, errors swallowed) so a search or selection never blocks or fails. Weights are resolved from a ranking_weights table (exactly one active row, partial unique index on active), falling back to env config (RANK_WEIGHT_*), then shipped constants. The API ranker re-reads the active row on an interval (RANK_WEIGHTS_REFRESH_INTERVAL, default 2m, 0 disables) and atomically swaps it into the live blend, so an approved retune applies without a redeploy. An admin endpoint (POST /backstage/locations/ranking-weights, gated by TomodaAdmin, input-validated to [0,1] and not all-zero) applies a cmd/rankertune -harvest recommendation. A DB read failure keeps the current vector; the read never blocks startup or drops the ranker to defaults.

Trade-offs. Two label tables to prune (a 24h cron bounds them at 180 days), plus the weights table (append-only history, one active row). The refresh is eventually-consistent within one interval; that window is well inside the human-gated retune loop.

Web rendering: unified Expo SSR (output: "server")

Decision. The web target moves from a client-rendered SPA (output: "single", with a static export for marketing pages) to server-side rendering on the single Expo Router codebase (output: "server"), deployed to Cloudflare Workers via expo-server/adapter/workerd. One React tree renders for humans and crawlers alike, and per-route title, meta, and JSON-LD come from the components. This retires both SEO workarounds: the post-export meta patch (frontend/scripts/release/seo-meta.mjs) and the crawler-vs-human User-Agent split in the edge link-preview worker. Gated behind the Expo SDK 55 → 58 upgrade, since output: "server" is stable only on SDK 58+.

Context. Public content (events, places, profiles) must rank and unfurl, but a client-rendered SPA ships an empty shell to crawlers. The brand term is already served by the static export; the unmet need is content-discovery ranking of entity pages, which requires real server-rendered HTML. Keeping the app and its SEO web as one Expo codebase avoids maintaining a second web stack, at the cost of rendering React Native Web on the server. Google deprecated dynamic rendering (the UA split) in favor of server-side rendering, static rendering, or hydration.

Rationale. Server rendering is the recommended path, and one codebase keeps a lean team's maintenance low. A viability spike confirmed the app's native runtime (reanimated, Skia, gesture-handler, true-sheet, WebSocket) builds and serves under server output without crashing, so the blockers are structural, not a wall. Robustness is enforced by explicit invariants, not convention:

  • Graceful degradation. A server-render error on any route falls back to the client shell, never a 5xx to the user; the app always boots client-side.
  • Server auth is settled-anonymous. With no credential present the tree renders the logged-out branch synchronously (no spinner, no authed data server-side); authed data is fetched only after hydration.
  • Per-request isolation. A per-request QueryClient with dehydrate/HydrationBoundary; public data is prefetched on the server and hydrated, so the client does not refetch.
  • SSR-safety is a build gate, not tribal knowledge. A lint rule bans module-scope and render-time browser globals, and a CI job runs the server export and smoke-renders the key public routes, asserting real content, so a server-unsafe import fails the build instead of reaching production.
  • Edge caching. Public responses carry s-maxage and are cached at the edge keyed by path + locale; authed responses pass through uncached.
  • Entity pages gain human-readable slugs and a dynamic sitemap driven by the internal/privacy visibility predicates.

Trade-offs. A new always-on server tier (deploys, scaling, cold starts, monitoring) replaces static files that essentially cannot fail; the graceful-degradation and edge-cache invariants bound that risk. Every future dependency that touches the DOM or a native module at import becomes a potential SSR break: the CI gate catches it, but it is a permanent tax. The SDK 55 → 58 upgrade (three majors, RN 0.83 → 0.88, native re-validation) is a hard prerequisite. The native iOS and Android apps, the Go API, and the design are unaffected; this is a web-rendering change only.

H3 is the app-wide cell vocabulary, computed in Postgres

Decision. Spatial cells are H3 hexagons, computed inside Postgres with the h3-pg extension (h3, h3_postgis), not in Go. The harvest ledger is the first user: harvest.CellGrid is implemented over SQL (h3_latlng_to_cell, h3_cell_to_latlng, h3_grid_disk, h3_cell_to_parent, h3_cell_to_boundary_geometry for the share of a cell a ring covers), and the old geohash grid is gone. Resolutions: 9 for picker rings up to 300 m, 8 for 500 m rings and nearby text lookups, 7 for the area text cache.

Context. Geohash cells are rectangles of uneven width, and their neighbours are awkward at cell edges, which matters once a ring spills into adjacent cells. A hexagonal grid has uniform neighbour distance and a clean parent hierarchy, so cell-keyed fills, the reach of a ring and coarser caches share one vocabulary.

Rationale. Computing cells in SQL keeps cgo and a native library out of the Go build, and lets queries join and filter on the same cell function. Nothing ran in production, so the tile key format changed with no compatibility shim.

Trade-offs. Every environment's Postgres image must carry h3-pg, and the migration runs CREATE EXTENSION IF NOT EXISTS, which is a no-op when the platform pre-creates it. A cell lookup is a database round trip (cell centres are memoised in process). The image builds the h3-pg 4.5.0 release (H3 core 4.5.0, fetched by its CMake with a checksum) and verifies the tarball against a pinned SHA-256.