mrtdown-site

Community-run transit monitoring for Singapore MRT/LRT disruptions.

mrtdown-site is a TanStack Start React app deployed to Cloudflare Workers. The app reads canonical mrtdown data through a Postgres/PostGIS-backed read model populated from data archives.

Stack

• React 19, TanStack Start, TanStack Router, and Vite.
• Cloudflare Workers, Workflows, Hyperdrive, and Wrangler.
• Postgres/PostGIS with Drizzle ORM and Drizzle Kit migrations.
• Biome, TypeScript, and Vitest for quality checks.

Local Development

1. Install dependencies:

   npm install

2. Create local environment variables:

   cp .env.example .env

   Keep VITE_ROOT_URL=http://localhost:3000 for local work. Add DATABASE_URL for database scripts; the local Wrangler Hyperdrive binding points at the same connection string:

   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mrtdown-db

3. Start a local Postgres database with PostGIS enabled, then run migrations and seed fixture data:

   npm run db:migrate
   npm run db:seed:fixtures

4. Start the app:

   npm run dev

   Visit http://localhost:3000.

Useful Scripts

• npm run dev: start the Vite dev server.
• npm run build: build the app.
• npm run deploy: build and deploy with Wrangler.
• npm run typecheck: run TypeScript without emitting files.
• npm run lint: run Biome linting.
• npm run format:check: check formatting across the repository.
• npm run test:run: run Vitest once.
• npm run verify: run typecheck, lint, formatting check, migration drift check, and tests.
• npm run db:generate: generate Drizzle migrations after schema changes.
• npm run db:generate:check: verify schema changes do not require a new migration.
• npm run dev:pull: trigger the local pull workflow endpoint while the dev server is running.

Project Layout

• app/routes: file-based routes, route loaders, page metadata, and API routes.
• app/util/*.functions.ts: TanStack server functions used by loaders and client code.
• app/util/db.queries.ts: DB-backed read model queries.
• app/db: Drizzle schema, enum helpers, and database connection setup.
• app/workflows/pull: Cloudflare Workflow code that stages and promotes canonical data.
• app/components: reusable UI and page-level components.
• docs: architecture, data pipeline, quality, and generated-file notes.

Data Flow

Canonical mrtdown archive data is fetched by the pull workflow, inserted into *_next staging tables, promoted into normalized live tables, and read by server functions through app/util/db.queries.ts.

The generated MRTDown API client has been retired. Server-side reads use the DB-backed query layer, with canonical domain types coming from @mrtdown/core where possible.

Generated Files

Do not hand-edit generated files unless the task is explicitly about generated output. Regenerate them through the relevant script or tool, then review the produced diff.

• app/routeTree.gen.ts: generated by TanStack Router tooling.
• drizzle/**: generated by Drizzle Kit with npm run db:generate.
• app/components/StationMap/components/Map*.tsx: mechanically converted station map snapshots.

See docs/GENERATED_FILES.md for more detail.

Documentation

• docs/ARCHITECTURE.md: current app architecture and deployment branch mapping.
• docs/DATA_PIPELINE.md: canonical data pull and read model flow.
• docs/QUALITY.md: verification harness and current test gaps.
• docs/OVERHAUL_BASELINE.md: historical baseline for the read-model migration.
• docs/plans/README.md: conventions for checked-in execution plans.
• docs/plans/active/: active multi-phase work, including read-model overhaul and production performance plans.
• docs/investigations/: dated investigation notes that inform plans and architecture docs.

Contributions

Run npm run verify before publishing changes. Use narrower commands such as npm run typecheck, npm run lint, npm run format:check, and npm run test:run while iterating.

Pull request titles should follow Conventional Commits, for example feat: add station history filters or fix: handle missing fact coverage.