The design decisions that shape Transit and the limits a contributor should know before relying on a behavior.

Reference Value
Subject and boundary Current architectural decisions with their tradeoffs, and current limitations backed by source. Planned work lives in the project roadmap, not here.
Verified source Repository tree at main 9733eb26d92533f56cdc8bc46b81b93fbb5987c8, checked November 10, 2026. Production payload facts come from public /data/v1 files read November 7, 2026.
Support state Decisions describe current source and tracked configuration. The deployment gaps below stay explicit; source, deployed and accepted behavior are separate.

Key decisions

Decision Why Tradeoff
Serve transit data through published JSON snapshots No public database credentials; object delivery caches and scales Answers depend on precomputed payloads; new questions may need a contract change
Keep Bronze raw bytes as the replay source Rebuild and audit Silver/Gold against exact inputs Default retention bounds recovery depth to 30 days
Thin realtime Silver with longer Gold rollups Keeps operational detail bounded Some repairs require Bronze replay before Gold rebuild; retained aggregates do not guarantee retained inputs
Pool exact sums and counts Multi-day means remain exact Counts and sums must be retained together; unknown contributing state keeps the result unknown
Immutable historic graph with conditional root activation One complete generation is reachable Live/static remain mutable and may expose mixed files; DB commit and remote activation are separate boundaries
Per-provider, per-tier PostgreSQL publication lanes Competing publishers fail fast The lane cannot fence remote writes already in flight after DB ownership is lost
Honest absence Missing, stale, unsupported and not-applicable values never become reassuring zeros Every consumer must design and test explicit states
One reliability verdict module Lines, stops and network use one classification At n≥30, exact counts produce a 95% Wilson interval; otherwise use valid published bounds without reconstructing counts. Reliable needs lower bound ≥80.0 and shown rate ≥80; an upper bound <80 gives patchy at shown rate ≥60, otherwise unreliable. The crossing range, upper edge 80.0, missing/partial/reversed/non-finite/out-of-range bounds and n<30 remain tentative. Only patchy/unreliable are problem lines. Classify before display rounding and include sample size in tentative sentences
Per-family health with accepted serving capture age A new publication or raw download must not conceal stale agency data Five states: never-loaded, live, retained-stale, retrying, failed-no-data. Unknown retained age stays stale; retrying after a failure takes precedence while the new attempt loads. Publication TTL, capture age and refresh failure are independent
Partial stalls use a caution One stopped family must not claim a whole-feed outage Whole-feed outage requires every active family stale. Supported alert data is included; unsupported OC Transpo alerts are excluded.
Remember the bulk content-section choice; keep tools independent First visits on pages with at least two eligible content sections and the bulk control start collapsed with Expand all active; the TOC card starts open The bulk action stores expanded/collapsed in localStorage sections-choice across pages and visits. Individual toggles are view-local. Independent panels and map tools are excluded; map controls/detail rails and panel width use their own settings. Server markup and boot recovery keep pending sections readable on code failure or a five-second initialization stall without overwriting the saved choice. EN/FR device-storage copy describes these preferences
Transit owns locale/header copy Shared UI ships no product words Copy changes live in locale files; Sheet requires localized close copy
One released shared-design version Tokens, primitives, station-tab look and motion policy stay aligned across consumers All eight @yesid packages pin v0.39.1 from yesid-dev/yesid.design (main 4fcc6c01, #703). API-report/migration-note changes rehearse on rc.N in a draft adoption PR in all three consumers (Transit, yesid.dev, yesid.login) before stable release; the same PR then switches to stable. Shared fixes wait for upstream release and consumer checks
SvelteKit 3 with an app-owned fixed-data guard The app keeps the supported Kit line while fixed JSON must finish before navigation commits Kit 3.1.1's fixed JSON path needs pageDataFetch to read a clone; deferred streams remain untouched. One extra clone/parse for matching responses; real-Kit built-output tests guard upgrades.
Keep the Bits UI touch patch Outside touch dismissal must preserve consumer interactions The patch targets exactly 2.20.4 and needs revalidation or removal on upgrade
Scheduled batch jobs on Actions, realtime on one VM Simple operation without slowing the live cadence Actions needs DB reachability; VM images require separate host activation. Daily Warm policy/receipts belong to daily_run, not inline workflow scripts
Keep live capture at 30 seconds or faster Yesito refused slowing it to 60 seconds to save cost on October 30, 2026. STM and OC Transpo vehicle positions are polled every 20 seconds after #746. STM is phase-aligned to its agency's rebuilds; OC is unphased. Faster polling does not change the agency's publication cadence More capture and publish work per hour on the VM and storage
KPI v1 is an additive agreement The proxy, probe and consuming hero distinguish valid, complete and unavailable readings One summary per provider through ?provider, defaulting to STM; stale vehicle anchor yields pipeline_cold/503. Trip/network lanes can be null independently. The consumer holds one failed/incomplete poll before demo on the second; endpoint checks do not prove that UI policy
Truthful web health and explicit failure routing Public failures reach a deduplicated owner-routed issue /health tests one STM manifest read and reports version, not feed freshness. New issues mention the owner and attempt assignment; email receipt depends on notification preferences
Observe realtime worker starts outside the feed path A crash-and-restart loop must reach the owner without slowing or blocking capture Each run-realtime-worker start increments core.worker_starts through a subprocess bounded to five seconds; failure logs one warning and capture continues. The Worker Start Probe reads the table every 15 minutes in a read-only transaction and opens or comments on a per-provider worker-restart-alert issue. A deliberate restart or rollout also alerts; the count is startup evidence, not exit-code evidence
Application errors without invocation records Diagnosis must not retain searched addresses in routine request records Both Worker configs redact queries, disable invocation logs, traces and issues; logging configuration is source evidence
Weekly cross-site links without contact sends Check the site's cross-links without synthetic messages or paid service Monday 10:37 UTC, bounded pages and pinned lychee. Web3Forms blocks headless browsers; owner chose no automatic real contact send. Manual pass is not first-scheduled-run evidence
Repository-owned CI helpers and local lockfile attempts Repository-owned CI helpers support portable contributor commands Try intended dependency resolution on the native host; pinned Linux frozen install decides. Unknown classifier paths run DB checks; docs-only summaries may represent intentionally skipped work

Current limitations