Skip to content

Fork room-tba

Room TBA is the flagship: an open-source campus map and class finder. It is a Bun + Astro app with a Postgres (Supabase or PGlite) backend, a MapLibre map, an in-app editor, and a PWA that works offline.

Read the in-app guide first. The fork itself ships a wiki page at room-tba.<your-domain>/wiki/fork-for-your-campus with exact file paths, and a data guide at docs/fork-data-guide.md in the repo. This page is the 10,000-ft version; those are the ground truth.

Keep (the engine): map UI, search, side panel, pin flyouts, PGlite offline cache, editor + suggest-an-edit queue, course planner, personal schedule routing, events, alias matching, share links, the Drizzle schema.

Replace (UPLB-only):

Thing Where
Site name/URL/description src/lib/site.ts, src/campus.config.ts, astro.config.mjs
Map bounds, camera, terrain, transit src/campus.config.ts
Community links (Discord, Messenger, org) src/constants/community-links.ts
Building/room seed data public/room_info.json, your database
Campus transit routes src/constants/jeepney-routes.ts + jeepney-geometries.json
UPLB registrar importers scripts/import-amis-classes.ts, import-final-exams.ts, import-osa-organizations.ts, import-campus-office-directory.ts
UPLB wiki page src/pages/wiki/section-times.astro
  • GitHub account, Bun 1.3+
  • A Postgres database — Supabase free tier works
  • A MapTiler key for map tiles (free tier exists)
  • Your campus data: building list with coordinates, room codes, class schedules from your registrar
  • A deploy target — Vercel free tier works (the app is built for the Vercel adapter)

One-click option: create your repo from bulsutools/room-tba-template (Use this template), then git clone it and git remote add upstream git@github.com:uplbtools/room-tba.git if you want syncs.

Fork option:

Terminal window
gh repo fork uplbtools/room-tba --org <your-org>
git clone git@github.com:<your-org>/room-tba.git
cd room-tba
cp .env.example .env.local
  1. Database. Create a Supabase project, copy the session pooler connection string into DATABASE_URL, and set ADMIN_SESSION_SECRET to 32+ random chars.
  2. Schema. bun install && bunx drizzle-kit push
  3. Campus config. bun run fork:init — interactive script that rewrites src/campus.config.ts (site, map bounds, camera, terrain, transit, community links). Refuses to run on a dirty tree; --force overrides.
  4. Delete/replace UPLB data per the table above. You can keep the import scripts as reference while you write your own.
  5. Seed and verify. bun run seed:sample loads a fictional “Evergreen Park College” dataset so you can see the whole engine working before your real data exists. Then bun dev → http://localhost:4321.

You do not need a custom importer on day one:

  • Buildings/rooms/orgs/places: the in-app editor (/?editor=login) is the day-to-day tool. First login with ADMIN_PASSWORD bootstraps admin.
  • Bulk first load: copy data/sample-campus/campus.json, replace entries, adapt scripts/seed-sample-campus.ts.
  • Class schedules: bun run import:classes-generic -- path/to/classes.csv takes any flattened registrar export — one row per meeting slot with course_code, section, type, days, start, end, room_code, term_id. Upserts by natural key; --replace-term does a clean refresh. Full column reference: docs/fork-data-guide.md.

bun run build prerenders pages from the DB, so DATABASE_URL must be set at build time. Deploy to Vercel (import the repo, add env vars) or any Node host.

bulsutools/room-tba is a live fork for Bulacan State University Malolos — useful as a reference for what a real fork looks like (colleges-only seed, editor-driven data entry, transit disabled until routes are added).