Introducing a new way to review your PRs.

Read the announcement

koala73 / worldmonitor

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

View on GitHub

29 documents · Updated Nov 20, 2026

docs / backend-gateway-routing

Backend gateway routing

The backend gateway is the common boundary for WorldMonitor API requests. It applies origin, identity, access, input, capacity, retry, cache, and error rules before a domain handler runs. The handlers then turn prepared data, provider results, and product rules into safe responses for the application and its partner clients. See also API platform and domain API routes.

Gateway boundary

The gateway gives every API domain one request policy while each domain handler owns product behavior. Domain entry points connect generated RPC routes to handlers through createDomainGateway; the same boundary also serves Markdown twins without forwarding caller credentials. This keeps transport rules consistent while allowing each product area to choose its own data source and response meaning (server/gateway.ts• L703-708, server/gateway.ts• L1093-1121).

The boundary supports public reads, account reads, paid analysis, provider-backed searches, and mutations. It separates authentication from entitlement. A valid identity therefore does not by itself grant a paid route, a longer history window, or access to another account's data.

Request flow

The request flow moves from transport checks to identity and access checks, then to route work and response mediation. An early failure stops later service work.

This diagram shows the main request path.

flowchart TD
    A[Client request] --> B[Origin and CORS policy]
    B --> C[Remove untrusted markers]
    C --> D{Trusted internal request?}
    D -->|Yes| E[Verify signature and replay proof]
    D -->|No| F[Resolve session or API key]
    E --> G[Apply access and capacity rules]
    F --> G
    G -->|Denied| H[Mapped HTTP error]
    G -->|Allowed| I[Match route and validate input]
    I --> J[Run domain handler]
    J --> K[Apply cache, freshness, CORS, and usage rules]
    K --> L[HTTP response]

References: server/gateway.ts• L1171-1197 server/gateway.ts• L1312-1367 server/gateway.ts• L2290-2379 server/gateway.ts• L2830-2944

Trusted internal requests

Internal requests provide a narrow path for trusted services to call protected routes. The gateway removes client-supplied trust markers before it checks a signed request. It accepts the request only after it verifies the user, timestamp, nonce, request shape, and replay state. It then adds fresh trusted markers for the handler.

The signature binds the method, path, query, body, user, timestamp, and nonce. The signer and verifier use one canonical form. A replay-store outage returns a retryable 503 instead of accepting a request that cannot be made single-use. All public signature failures use the same 401 response, while server telemetry keeps the reason for diagnosis (server/gateway.ts• L1452-1627).

References: server/gateway.ts• L924-955 server/gateway.ts• L1388-1449 server/gateway.ts• L1452-1627 server/gateway.ts• L228-238

Identity and access

The gateway resolves browser sessions, API keys, internal MCP proofs, and limited operator or relay credentials into server-owned identity. Authentication answers who is calling. Entitlement answers which product capability that identity may use. The two answers remain separate so a valid caller does not receive access that its plan does not allow.

Access sessions

An access session is a verified signed-in identity. The gateway can use its user, organization, role, and session state for route access and caller limits. Invalid credentials resolve as an authentication denial. A session verification outage remains an unverifiable state and becomes a retryable 503, rather than a false anonymous request or a misleading plan denial (server/gateway.ts• L1696-1716, server/…/auth-session.ts• L19-106).

User API keys resolve to their owner through a protected lookup. A missing or revoked key is an authentication denial. A lookup outage remains a retryable service failure so a client does not rotate a valid key during a backend incident (server/gateway.ts• L1734-1824, server/…/user-api-key.ts• L36-166).

Entitlement access

Entitlement is route-specific. A route can require a paid tier, API access, Pro MCP access, export, embedding, or a model budget. Confirmed missing access is a terminal denial. A pending renewal or failed billing lookup is a verification failure and does not become a misleading upgrade prompt (server/…/entitlement-check.ts• L197-232, server/…/entitlement-check.ts• L820-939).

The gateway reserves direct model budget before provider work and releases it when no answer is served. This keeps failed, rejected, and duplicate work from consuming a customer's daily allowance (server/gateway.ts• L2696-2787, server/gateway.ts• L2918-2927).

Account-private sessions

Account-private routes use the verified browser session as the account identity. The current route set includes sent alert history. An API key cannot choose which account is read, even when a request carries both a key and a browser credential. The route is no-store so one user's response cannot enter a shared cache (server/gateway.ts• L605-627, server/gateway.ts• L1742-1757, server/gateway.ts• L2942-2985).

Anonymous routes

Some routes are public by product design. Lead capture, public trust views, selected claim searches, and selected feedback paths do not require a session. They use their own input checks, endpoint limits, bot checks, or review controls instead of treating an anonymous session token as proof of identity (server/gateway.ts• L631-678).

References: server/…/auth-session.ts• L19-106 server/…/user-api-key.ts• L36-166 server/…/entitlement-check.ts• L197-232 server/gateway.ts• L605-678 server/gateway.ts• L1696-1824

Routing and validation

Routing maps a normalized method and path to one service operation. Validation turns the generated request contract and product rules into a client-facing input boundary before provider or product work begins.

Route matching

The router distinguishes an unknown path from a known path with an unsupported method. It supports static and parameter paths and reports allowed methods for 405 Method not allowed responses. HEAD follows a GET route but returns no body (server/router.ts• L49-134).

Older clients can send a bounded scalar JSON body with POST to a GET route. The gateway converts only scalar fields and scalar arrays into query fields. Nested values, malformed JSON, oversized bodies, and oversized arrays are rejected without applying a partial conversion (server/gateway.ts• L711-839).

References: server/router.ts• L49-134 server/gateway.ts• L711-839 server/gateway.ts• L2144-2198

Input contracts

Generated schemas provide the common request shape. Handlers add checks that depend on product meaning, access, provider cost, or transport. The runtime boundary rejects bad types, enum values, ranges, lengths, repeated values, and malformed nested data before a handler spends provider or model budget (server/request-validator.ts• L45-63, server/request-validator.ts• L105-223, server/request-validator.ts• L347-386).

The domain handlers keep invalid input separate from unavailable source data. This lets clients distinguish a bad request from a valid request whose data source is not ready (server/…/list-media-perspective.ts• L38-62, server/…/list-country-headlines.ts• L39-57).

References: server/request-validator.ts• L45-63 server/request-validator.ts• L105-223 server/…/list-media-perspective.ts• L38-62 server/…/list-country-headlines.ts• L39-57

Request protection

The gateway protects shared capacity and paid provider work with endpoint, global, account, and daily limits. Explicit endpoint policies fail closed when their abuse store is unavailable. Ordinary reads can use an availability-first fallback. Confirmed principals can receive a user-scoped budget instead of sharing an IP bucket (server/…/rate-limit.ts• L264-344, server/…/rate-limit.ts• L902-939, server/gateway.ts• L2358-2687).

POST mutations can opt into idempotency. The gateway scopes a key to the caller, replays a completed result without charging again, rejects a concurrent duplicate, and rejects reuse with a different body. A store outage disables this convenience rather than blocking valid traffic (server/…/idempotency.ts• L1-29, server/…/idempotency.ts• L302-431, server/gateway.ts• L2310-2355).

Server fan-out spends the initiating caller's budget before dispatch and refuses an unattributed sub-request. The inner request must stay within the same origin and use one-use admission (server/…/server-sub-request-dispatch.ts• L23-74, server/gateway.ts• L2361-2379).

References: server/…/rate-limit.ts• L239-344 server/…/rate-limit.ts• L410-535 server/…/server-sub-request-dispatch.ts• L23-74 server/…/idempotency.ts• L1-431 server/gateway.ts• L2310-2687

CORS and error mapping

Cross-origin policy controls which browser origins can read responses. Error mapping gives clients stable HTTP meaning without exposing provider details or turning a transient outage into a false empty result.

Cross-origin policy

Production allows the WorldMonitor application, scoped preview deployments, and Tauri origins. Development also allows local origins. The policy covers headers used by sessions, API keys, desktop authentication, MCP, and retry flows. It exposes response metadata needed for limits and diagnostics (server/cors.ts• L8-87).

An OPTIONS preflight can succeed before the real origin check. A present but disallowed origin receives a readable 403. Origin-aware responses retain Vary: Origin. Requests without an origin do not receive a shared browser cache hit that could skip authentication (server/gateway.ts• L1312-1367, server/gateway.ts• L2987-3005).

References: server/cors.ts• L8-87 server/gateway.ts• L1312-1367 server/gateway.ts• L2942-3005

Error contracts

The shared mapper converts validation, authentication, entitlement, rate, upstream, and unexpected failures into stable HTTP responses. Expected client messages remain safe to show. Most server failures use a generic message. Retryable results can carry retry timing and billing state (server/error-mapper.ts• L45-169).

Handlers use explicit result states when a valid request cannot produce complete data. The gateway reads those signals and prevents failed or degraded results from becoming long-lived shared cache entries. This keeps unavailable data distinct from a successful empty result (server/…/cache-contract.ts• L26-67, server/gateway.ts• L2942-3005).

References: server/error-mapper.ts• L45-169 server/…/cache-contract.ts• L26-67 server/gateway.ts• L2880-2927

Response mediation

Response mediation joins handler results to transport rules. It selects cache privacy and freshness, applies projections, adds retry and diagnostic headers, records usage, and keeps provider or model failures visible to the caller.

Cache and freshness

The gateway assigns a freshness tier to successful GET responses. Public data can use browser and edge caches. Credentialed, premium, account-private, and no-store routes remain private. A handler can override the tier when its body says the data is stale, partial, unavailable, or unsafe to share (server/gateway.ts• L240-279, server/gateway.ts• L2942-3005).

The route policy keeps fast news views inside their rebuild cadence. Country headline and media perspective results use short-lived shared caching, while claim search and private searches stay no-store or avoid caching when coverage is incomplete (server/gateway.ts• L452-475, server/…/list-country-headlines.ts• L90-92, server/…/list-media-perspective.ts• L284-303, server/…/search-claim-headlines.ts• L203-212).

Cache identity follows the returned view. A requested JSON projection is applied before the gateway computes the response validator. Public projections share the MCP expression contract and are bounded by expression complexity and output size (server/…/response-projection.ts• L4-120, server/gateway.ts• L3012-3081).

References: server/gateway.ts• L240-279 server/gateway.ts• L2942-3005 server/gateway.ts• L3012-3081 server/…/list-country-headlines.ts• L90-92 server/…/list-media-perspective.ts• L284-303

Usage and provider mediation

Usage telemetry records route outcome, identity kind, plan, account pool, cache tier, execution plane, and failure reason without changing API availability. It separates malformed requests, entitlement outages, replay-store failures, account limits, and rate-limit degradation so operators can distinguish caller faults from platform faults (server/…/usage-identity.ts• L11-69, server/…/usage.ts• L65-203, server/gateway.ts• L1264-1310).

Provider-backed handlers use shared relay credentials and bounded cache access. A provider error is not a valid empty result. A route can return partial or degraded data, while failed work stays out of successful caches (server/…/relay.ts• L3-34, server/…/list-feed-digest.ts• L824-845, server/…/list-media-perspective.ts• L294-303).

References: server/…/usage-identity.ts• L11-69 server/…/usage.ts• L65-203 server/…/relay.ts• L3-34 server/…/list-feed-digest.ts• L824-845 server/…/list-media-perspective.ts• L294-303

AI provider routing

AI provider routing applies customer-specific rules to calls that carry caller text. A signed-in user's policy can select an ordered provider allowlist. A missing or failed policy lookup produces an empty allowlist, so the system stops instead of sending the text to an unapproved provider chain (server/…/ai-routing-policy.ts• L8-151).

Model-bound WorldMonitor context is also treated as untrusted input. Feed, market, country, and user text is sanitized and placed into bounded data blocks before it reaches the model. The context assembler can continue with partial source coverage and reports which context sources were active (server/…/chat-analyst-context.ts• L96-125, server/…/chat-analyst-context.ts• L1141-1161, server/…/chat-analyst-context.ts• L1192-1341).

References: server/…/ai-routing-policy.ts• L8-151 server/…/llm.ts• L47-81 server/…/chat-analyst-context.ts• L96-125 server/…/chat-analyst-context.ts• L1192-1341

WorldMonitor service handlers

WorldMonitor handlers turn generated RPC operations into product capabilities. The gateway supplies the shared request boundary. Each handler then combines prepared data, caches, relays, external providers, or model work according to its product contract.

Service domains

The service groups expose broad product capabilities:

Service groupProduct purpose
Market and economicPrices, company analysis, capital flows, debt, indicators, rates, food markets, and procurement views
IntelligenceCountry facts, risk, feeds, signals, energy profiles, port activity, briefs, history, and situation analysis
News and trustFeed digests, headline search, delivered alerts, claim coverage, fact-check citations, label history, and reader reports
Aviation and militaryAirport operations, flight searches, aircraft positions, emergency signals, and military flight views
Infrastructure, safety, and natural eventsNetwork health, outages, hazards, public safety, temporal anomalies, and source freshness
Supply chain and shippingChokepoint intelligence, trade products, route views, tenant webhooks, and partner actions
Forecast, resilience, and predictionSimulations, forecasts, country comparisons, resilience measures, and prediction markets
Sanctions and displacementEntity screening, sanctions pressure, population movement, and cross-border movement views
Leads, feedback, and account actionsAnonymous interest capture, agent reports, and protected user or partner actions

Generated handlers make the mapping from an RPC contract to a product capability explicit. News and trade handlers register their operations in the same route surface as intelligence, orbital, and supply-chain handlers (server/…/handler.ts• L1-34, server/…/handler.ts• L1-23, server/…/handler.ts• L1-12, server/…/handler.ts• L1-39).

References: server/…/handler.ts• L1-34 server/…/handler.ts• L1-23 server/…/handler.ts• L1-12 server/…/handler.ts• L1-39

Data availability

Handlers preserve the difference between no matching data and no trustworthy data. Seeded reads return an explicit unavailable or partial state when a canonical snapshot cannot be read. Multi-source reads retain source coverage so a missing source is not shown as a healthy zero (server/…/get-monthly-sitc-trade.ts• L94-135, server/…/get-food-prices.ts• L6-13).

Provider reads use bounded fallbacks. A route can preserve a last-known result, recover one missing detail, or return a degraded answer. It must not present a provider failure as an ordinary empty result or place the failure in a long-lived shared cache.

References: server/…/cache-contract.ts• L26-67 server/…/get-monthly-sitc-trade.ts• L94-135 server/…/get-food-prices.ts• L6-13 server/…/get-country-products.ts• L358-389

News digest coverage

The news digest builds a shared view from many feeds while keeping edition and language choices on the read path. Feed definitions state where a source belongs, which languages can reach it, which feeds should start first when time is limited, and which deeper feeds support claim search (server/…/_feeds.ts• L6-87).

Each build records feed and category coverage. It distinguishes completed, empty, timed out, relay failure, deadline-aborted, and not-started work. A direct feed read can fall back to a relay, while HTML challenge pages and malformed bodies are rejected instead of being cached as empty news (server/…/list-feed-digest.ts• L824-845, server/…/list-feed-digest.ts• L1017-1182).

The digest applies operator URL revocations at serve time. When a rebuild is empty or fails, it can serve an accepted last-good snapshot for up to six hours. The snapshot is replaced only when the candidate is not materially narrower. Fresh, durable, and warm-isolate fallback paths all apply revocations and mark stale or unavailable coverage (server/…/list-feed-digest.ts• L268-380, server/…/list-feed-digest.ts• L2527-2637, server/…/_lastgood.ts• L259-321). The gateway gives the digest a fast public cache tier so the edge cache stays within the digest refresh cadence (server/gateway.ts• L452-468).

References: server/…/_feeds.ts• L6-114 server/…/_rss-cache.ts• L1-40 server/…/list-feed-digest.ts• L1017-1182 server/…/list-feed-digest.ts• L2474-2779 server/…/_lastgood.ts• L259-321 server/gateway.ts• L452-468

Country headline views

Country headline views read the full English feed cache and select recent articles that mention each requested country. They remove revoked or malformed links, limit each country to a small set of headlines, and report whether feed coverage is complete, partial, or unavailable (server/…/list-country-headlines.ts• L18-36, server/…/list-country-headlines.ts• L39-92).

The feed cache keeps a larger country pool apart from the small digest view. A matching parse timestamp prevents a stale pool from being joined to a newer feed result. The route uses a shared fast tier only for complete results; incomplete coverage is marked no-store (server/…/_rss-cache.ts• L5-28, server/…/list-country-headlines.ts• L51-92).

References: server/…/list-country-headlines.ts• L18-92 server/…/_rss-cache.ts• L1-36 server/gateway.ts• L452-468

Media perspective views

Media perspective views group recent coverage of a subject country by outlet home country and audience. The service builds one unfiltered grouping for each subject and time window, then applies outlet-country and audience filters at serve time so filter choices do not create a large cache-key set (server/…/list-media-perspective.ts• L31-72, server/…/list-media-perspective.ts• L195-275).

The view keeps publisher family diversity visible and carries source tier, ownership, state affiliation, and propaganda-risk signals with each headline. Complete results can be cached for five minutes. Partial results use a short cache and no-store response behavior so a feed outage is not presented as a stable view (server/…/list-media-perspective.ts• L109-153, server/…/list-media-perspective.ts• L277-303).

References: server/…/list-media-perspective.ts• L31-72 server/…/list-media-perspective.ts• L109-153 server/…/list-media-perspective.ts• L195-303 server/…/_rss-cache.ts• L12-28

Claim headline search supports verification flows by searching the fresh headline pool rather than only the small digest that reached the dashboard. It reads the full feed cache and optional deeper publisher feeds, removes revoked or stale rows, deduplicates native and depth results, and returns candidate headlines for claim matching (server/…/search-claim-headlines.ts• L15-21, server/…/search-claim-headlines.ts• L88-152).

The search shares a short-lived in-isolate pool across claims. Missing feed caches are normal and produce a partial result when some feeds were read. A search that could not run is unavailable and is kept out of caches (server/…/search-claim-headlines.ts• L155-212).

References: server/…/search-claim-headlines.ts• L24-36 server/…/search-claim-headlines.ts• L88-212 server/…/_feeds.ts• L19-23 server/…/_rss-cache.ts• L1-28

Country intelligence briefs

Country intelligence briefs assemble shared news grounding for anonymous requests and caller-specific context for premium requests. The shared path uses one cache entry per country and language, while premium entries can include the caller's source and framework context (server/…/_country-brief-context.ts• L1-14, server/…/_country-brief-context.ts• L41-80).

The grounding path reads the English digest and checks the current revocation set before it selects country-relevant, non-editorial headlines. It sanitizes feed text before model use and returns empty grounding when the source or suppression check is not readable. This lets the brief still run without presenting unchecked news as trusted context (server/…/_country-brief-context.ts• L158-223).

References: server/…/_country-brief-context.ts• L1-14 server/…/_country-brief-context.ts• L41-80 server/…/_country-brief-context.ts• L158-223

Event classification

Event classification turns a headline into a bounded threat level and category for downstream news labels. It first checks a shared result cache, then uses the configured AI routing policy for a caller-supplied title when no valid result exists (server/…/classify-event.ts• L44-65, server/…/classify-event.ts• L100-170).

The response accepts only the shared level and category vocabulary. Invalid cached data or an unavailable model produces no classification and marks the response as unserved and unsafe to cache. Story-based digest labels and direct caller titles use separate cache namespaces so one input cannot overwrite the other (server/…/_shared.ts• L14-29, server/…/_shared.ts• L72-79, server/…/classify-event.ts• L172-197).

References: server/…/_shared.ts• L14-29 server/…/_shared.ts• L72-79 server/…/classify-event.ts• L44-65 server/…/classify-event.ts• L100-197

Delivered alert history

Delivered alert history lets a signed-in user find headlines that the alert service sent to that account. The gateway stamps the authenticated user ID; the handler does not accept a user ID in the request. It removes blocked notification links, applies the retention window, sorts by delivery time, and returns unavailable when the history or block list cannot be read (server/…/list-sent-alerts.ts• L22-37, server/…/list-sent-alerts.ts• L38-71).

This route is account-private and uncached. That contract prevents an API key from selecting another account and prevents a shared edge response from crossing account boundaries (server/gateway.ts• L605-627, server/gateway.ts• L450-458).

References: server/…/list-sent-alerts.ts• L22-71 server/gateway.ts• L605-627 server/gateway.ts• L450-458

Chat analyst context

The chat analyst assembles bounded context from prepared intelligence, market, energy, forecast, prediction, country, imagery, and news data. It runs independent reads together and marks the context as degraded when too many core sources are missing. Feed-derived text is sanitized before it enters a model prompt (server/…/chat-analyst-context.ts• L96-125, server/…/chat-analyst-context.ts• L1192-1341).

News retrieval separates places from topic terms. resolveGeoScope recognizes countries, aliases, demonyms, and broad or sub-regional phrases. matchPlaces then combines country mentions, region members, and digest categories. The analyst ranks place and topic matches, keeps a small number of topic-only articles, and reports a coverage gap when a named place has no matching headline (server/…/chat-analyst-geo-scope.ts• L146-165, server/…/chat-analyst-geo-scope.ts• L273-296, server/…/chat-analyst-context.ts• L1061-1138).

The analyst reads a materialized GDELT view and the shared English digest rather than fetching a live news provider for every question. If Redis or the revocation set cannot be read, it drops that grounding block instead of passing unchecked or stale content to the model (server/…/chat-analyst-context.ts• L789-821, server/…/chat-analyst-context.ts• L940-976, server/…/chat-analyst-context.ts• L1141-1161).

References: server/…/chat-analyst-context.ts• L789-976 server/…/chat-analyst-context.ts• L1061-1161 server/…/chat-analyst-context.ts• L1192-1341 server/…/chat-analyst-geo-scope.ts• L146-165 server/…/chat-analyst-geo-scope.ts• L273-296

Supply-chain product views

Country product views expose bilateral trade by product heading for paid callers. The handler validates the country and heading, reads a canonical catalog, and can add threshold partner detail or world-export scale for a requested heading. Extended headings remain supplementary, so their absence does not erase a valid core catalog (server/…/get-country-products.ts• L123-149, server/…/get-country-products.ts• L222-265).

When stored data is missing or stale, the handler can make bounded catalog and single-heading recovery attempts. It keeps cache failure, stale preservation, partial coverage, and missing data distinct. A failed supplementary read degrades partner detail to the leading set instead of turning a valid canonical response into a cache outage (server/…/get-country-products.ts• L281-323, server/…/get-country-products.ts• L358-389).

References: server/…/get-country-products.ts• L13-19 server/…/get-country-products.ts• L123-149 server/…/get-country-products.ts• L222-265 server/…/get-country-products.ts• L281-389

Monthly SITC trade

Monthly SITC trade provides a country history grouped by Standard International Trade Classification sections. The route currently serves supported prepared country coverage from a Railway seed. It normalizes default country, section, and month choices, then returns well-formed months in oldest-first order (server/…/get-monthly-sitc-trade.ts• L1-22, server/…/get-monthly-sitc-trade.ts• L47-91).

The response distinguishes invalid requests, countries without coverage, missing seeds, cache failure, and served data. This lets the client show “not covered” or “temporarily unavailable” without treating either state as a zero trade series (server/…/get-monthly-sitc-trade.ts• L24-30, server/…/get-monthly-sitc-trade.ts• L94-135).

References: server/…/get-monthly-sitc-trade.ts• L1-22 server/…/get-monthly-sitc-trade.ts• L47-91 server/…/get-monthly-sitc-trade.ts• L94-135 server/…/handler.ts• L1-23

Anonymous lead capture

Lead handlers accept anonymous enterprise requests because a visitor does not need an account to request contact. The gateway leaves the route outside session authentication. Turnstile, a honeypot, work-email rules, bounded fields, endpoint limits, and downstream throttles form the abuse boundary (server/gateway.ts• L631-645, server/…/submit-contact.ts• L127-176).

The handler stores an accepted lead in Convex before it sends an operations notice. Email delivery is secondary to the stored result, so a mail outage does not erase an accepted lead. Missing Convex configuration or a failed storage request is a service-unavailable result. Bot verification fails closed outside an explicit development policy (server/…/submit-contact.ts• L178-231, server/…/turnstile.ts• L7-53).

References: server/gateway.ts• L631-645 server/…/submit-contact.ts• L127-231 server/…/turnstile.ts• L7-53

Change checklist

When these files or sections are changed, remember to consider these:

  • A new or renamed RPC must stay aligned across its generated contract, route adapter, handler, access policy, cache tier, and REST or MCP exposure.
  • A new credential or trusted marker must be removed from inbound headers before the gateway rebuilds trusted context and must be included in cache privacy checks.
  • A route that becomes credentialed, premium, account-scoped, or redistribution-sensitive must not retain a shared cache tier.
  • Internal MCP signing and verification must keep path, query, body, timestamp, user, nonce, and replay rules identical.
  • Provider or model work must preserve endpoint limits, caller attribution, quota reservation, rollback, deadlines, and unserved-result meaning.
  • Server fan-out must keep same-origin checks, caller pre-charge, unattributed refusal, and one-use inner admission together.
  • Idempotency changes must keep caller scope, body hashing, replay headers, exempt paths, and OpenAPI behavior aligned.
  • A seeded reader and its producer must keep payload shape, source coverage, freshness, version, filter bounds, and unavailable-result meaning aligned.
  • News digest changes must keep feed language reachability, deeper claim-search feeds, attempt outcomes, revocation checks, last-good acceptance, stale markers, headline-history writes, and shared snapshot publication aligned.
  • RSS cache changes must keep the digest pool and the larger country pool tied to the same parse timestamp and freshness rules.
  • Country headline and media perspective changes must keep publisher identity, URL checks, country matching, source coverage, and no-store behavior aligned.
  • Claim search changes must keep native and depth-feed deduplication, revocation reads, bounded pool reuse, partial coverage, and anonymous route policy aligned.
  • Country brief changes must keep anonymous shared keys free of caller context, premium context hashes complete, prompt sanitization active, and fresh revocation checks in place.
  • Event classification changes must keep level and category vocabularies aligned across the handler, shared cache writers, digest readers, and model validation.
  • Account-private alert changes must keep gateway session identity, user-scoped storage, suppression checks, retention, and no-store behavior aligned.
  • Chat analyst changes must keep geographic scope parsing, digest categories, prompt sanitization, revocation checks, source degradation, and model routing aligned.
  • Lead changes must keep anonymous access, bot policy, work-email validation, downstream storage, and secondary email behavior aligned.

Important failure modes

TriggerConsequenceGuard
A caller sends a trusted identity or rate-limit markerA handler could use forged identity or charge another callerThe gateway strips markers and adds them only after trusted checks (server/gateway.ts• L924-955)
Internal MCP replay storage is unavailableA captured signed request could be reusedThe gateway returns a retryable 503 and fails closed (server/gateway.ts• L1542-1556)
Session, key, or entitlement verification cannot answerA valid customer could receive a false auth denial or upgrade promptVerification failures stay distinct from invalid credentials and lapsed access (server/gateway.ts• L1703-1708, server/…/entitlement-check.ts• L744-809)
A credentialed or account-private response uses a shared cacheOne caller's private data could reach another callerThe gateway forces private or no-store behavior for credentialed and account-private routes (server/gateway.ts• L2942-2985)
An explicit endpoint limiter is unavailableProvider or mutation work could run without its abuse budgetEndpoint policy fails closed with a degraded response (server/…/rate-limit.ts• L902-939)
A mutation retry reuses a key with a different bodyA client could receive the wrong result or repeat a side effectThe gateway hashes the body and rejects key reuse (server/…/idempotency.ts• L263-275)
A provider or seed read fails and returns an ordinary empty bodyAn outage could be cached or shown as valid empty dataHandlers expose unavailable or degraded state and suppress unsafe caching (server/…/cache-contract.ts• L26-49)
A digest rebuild is empty or failsClients could lose the last useful news view or see a false empty digestAccepted last-good snapshots and warm-isolate fallbacks are bounded, marked stale, and revocation-filtered (server/…/list-feed-digest.ts• L2595-2637, server/…/_lastgood.ts• L307-321)
The news suppression set cannot be readRevoked headlines could return from a cache or stale snapshotDigest, brief, and claim-search paths fail closed or return unavailable (server/…/list-feed-digest.ts• L2548-2558, server/…/_country-brief-context.ts• L207-223, server/…/search-claim-headlines.ts• L100-112)
A country pool is joined to a different feed parseOld or mismatched headlines could appear in country or perspective viewsReaders use the parse timestamp to accept only the matching country pool (server/…/_rss-cache.ts• L17-28)
Headline history or feed caches are unreadableSearch could look like “no matches” when it did not runCountry and claim views return explicit unavailable or partial coverage and avoid unsafe caching (server/…/list-country-headlines.ts• L47-55, server/…/search-claim-headlines.ts• L180-212)
A country brief uses a revoked or irrelevant headlineA model could ground a country brief in withdrawn or off-topic contentThe shared brief filters revocations and country relevance, then sanitizes the prompt lines (server/…/_country-brief-context.ts• L168-203)
A shared classification cache contains an invalid level or categoryThe dashboard could show an unsupported threat labelReaders validate the closed vocabularies before returning a classification (server/…/_shared.ts• L14-29, server/…/classify-event.ts• L178-197)
Feed or model text contains instruction-shaped contentA model could follow feed text as an instructionFeed-derived strings are sanitized and rendered inside bounded prompt blocks (server/…/_country-brief-context.ts• L194-203, server/…/chat-analyst-context.ts• L96-125)
Convex storage succeeds but notification email failsOperators may miss a lead even though the lead is storedStorage is completed first and email status is returned separately (server/…/submit-contact.ts• L185-231)

Key files

FileWhy to read it
server/gateway.tsShows the shared origin, identity, access, quota, routing, cache, and response flow.
server/router.tsShows path normalization, method matching, and 404 versus 405 behavior.
server/request-validator.tsShows the common runtime request boundary and bounded validation work.
server/…/auth-session.tsShows session resolution and the retryable meaning of verification failure.
server/…/entitlement-check.tsShows tier access and billing verification states.
server/…/rate-limit.tsShows endpoint budgets, caller attribution, fail-closed limits, and fan-out charging.
server/…/idempotency.tsShows mutation retry safety and caller-scoped replay.
server/cors.tsShows the browser origin and header policy.
server/error-mapper.tsShows stable client errors and upstream failure mapping.
server/…/cache-contract.tsShows which result states must not enter shared caches.
server/…/ai-routing-policy.tsShows customer provider restrictions and routing-aware model access.
server/…/handler.tsShows the news product operations exposed through the gateway.
server/…/list-feed-digest.tsShows feed assembly, coverage, revocation, and last-good serving.
server/…/_feeds.tsShows feed language reachability, edition definitions, and claim-search depth feeds.
server/…/_rss-cache.tsShows shared feed-cache keys, country-pool pairing, and freshness limits.
server/…/_lastgood.tsShows accepted snapshot and stale-serving policy.
server/…/list-country-headlines.tsShows country matching, feed coverage, and recent headline views.
server/…/list-media-perspective.tsShows outlet grouping, source signals, filters, and partial-result handling.
server/…/search-claim-headlines.tsShows full-pool claim search, depth feeds, deduplication, and coverage state.
server/…/_headline-history.tsShows served-headline retention, search, revocations, and index budgets.
server/…/search-headlines.tsShows free and archive search windows and caller charging.
server/…/list-sent-alerts.tsShows account-private alert history and suppression behavior.
server/…/_country-brief-context.tsShows shared country grounding, cache separation, revocation checks, and prompt-safe headlines.
server/…/_shared.tsShows classification vocabularies and shared cache identity.
server/…/classify-event.tsShows model-backed event classification and invalid-result handling.
server/…/chat-analyst-context.tsShows grounded analyst context, source degradation, and prompt-safe news retrieval.
server/…/chat-analyst-geo-scope.tsShows country and region scope used for headline matching.
server/…/food-prices.tsShows source normalization, freshness, baselines, and status meaning.
server/…/get-food-prices.tsShows multi-source food-price assembly and no-store fallback.
server/…/get-point-passes.tsShows point normalization, pass computation, archive matching, and partial-result handling.
server/…/get-country-products.tsShows premium product views, bounded recovery, supplementary evidence, and state labels.
server/…/get-monthly-sitc-trade.tsShows seeded monthly trade coverage and explicit unavailable reasons.
server/…/submit-contact.tsShows anonymous work-email validation, storage, and secondary notification.