Fork this for your campus

What you keep

The engine is generic. You do not rewrite these:

• The map UI, search bar, side panel, and pin flyouts.
• PGlite offline cache (the app answers "where is this room" with no signal).
• The editor and the suggest-an-edit review queue.
• The course planner and the personal-schedule routing.
• Events on the map, alias synonym matching, share links.
• The Drizzle schema. Tables for buildings, rooms, classes, aliases, events, organizations, places, colleges, dorms, jeepney_routes, and final exams are campus-shaped, not UPLB-shaped.

What is UPLB-only (you rip this out or replace it)

If a fork only changes the logo and the site name, it is still a UPLB app pointing at UPLB data. That is the thing the license line in the README is warning you about.

What you need before you start

• A GitHub account (to fork).
• Bun 1.3+ on your machine.
• A Supabase project. Free tier is fine for a small campus.
• A MapTiler key for vector and terrain tiles. Free tier exists; watch the quota.
• Your campus data: a building list with coordinates, room codes, class schedules from your registrar or SAIS equivalent, and a final-exam schedule if you want that panel.
• Somewhere to deploy. Vercel free tier works; the app is built for the Vercel adapter.

The actual steps

1. Fork and clone

Fork uplbtools/room-tba on GitHub, then:

git clone https://github.com/<your-org>/room-tba.git
cd room-tba
cp .env.example .env.local

2. Make a Supabase project and grab the URL

Create a project. In SQL settings, copy the session pooler connection string (the one ending in *.pooler.supabase.com). Paste it as DATABASE_URL in .env.local. Set ADMIN_PASSWORD to something long and random. You need it to log into the editor.

3. Install and create the tables

bun install
bunx drizzle-kit push

drizzle-kit push creates every table from drizzle/schema.ts in your Supabase Postgres. You start with an empty campus.

4. Run bun run fork:init, which rewrites src/campus.config.ts

bun run fork:init

The script asks for your campus name, site URL, map center, bounds, default zoom, and whether you want the 3D terrain and transit overlays, then regenerates the single config file. It refuses to run on a dirty git tree (pass --force to override) so the rewrite is easy to review. You can also edit the file by hand; these are its sections:

• campusSite: url, name, title, description.
• campusMap: maxBounds (the lng/lat box that keeps the camera on your campus) and defaultCamera (center: [lng, lat], zoom, pitch, bearing).
• campusTerrain: the 3D terrain source, bounds, and camera. enabled: false gives a flat map with no terrain controls anywhere.
• campusTransit: the campus transit overlay. enabled: false hides the map layer, sidebar entry, deep links, and sitemap entries; label renames the menu entry (UPLB says jeepney, yours may say shuttle).
• campusTestFixtures: coordinates the E2E suite seeds its test building and dorm at. Keep them inside your bounds and the Playwright suite runs unchanged.
• campusCommunity: your org, GitHub, Discord, and Messenger links. Delete entries you do not have.

The rest of the app (site.ts, map-terrain.ts, community-links.ts, astro.config.mjs, the transit UI, scripts/e2e-reset-db.ts) imports from here.

5. Delete or replace the UPLB data files

• Replace public/room_info.json with your buildings (or delete it and seed the DB directly).
• Replace the routes in src/constants/jeepney-routes.ts and jeepney-geometries.json with your campus transit, or leave them and set campusTransit.enabled: false.
• Delete the UPLB import scripts you cannot reuse: import-amis-classes.ts, import-final-exams.ts, import-osa-orgs.ts, import-campus-offices.ts. Keep them as reference while you write your own.
• Delete src/pages/wiki/section-times.astro (the UPLB section-code glossary) and its card on the wiki index.

6. Start the dev server

bun dev

Open http://localhost:4321. The map loads with your new center and bounds. Nothing is on it yet because the DB is empty.

7. Run fork:check to catch what you missed

bun run fork:check

Scans the repo for hardcoded UPLB strings you forgot to replace (uplb, uplb.tools, AMIS, Makiling, PSLH, the UPLB map center coords, Messenger invites, …). Reports file:line hits with hints. On a finished fork it should report zero. Wire it into your fork's CI (--silent for exit-code-only) so a stray UPLB string does not sneak back in on a merge from upstream.

Loading your own data

Two ways. Use both.

The in-app editor. Log in at /?editor=login with your ADMIN_PASSWORD. Drop pins, add buildings and rooms, set aliases. This is how you fix data day-to-day and how volunteers contribute without touching the DB.

A seed script. Run bun run seed:sample first. It loads a small fictional campus (data/sample-campus/) into an empty database so the whole app works before you have any real data. For your first real bulk load, replace the sample JSON with your campus and reuse scripts/seed-sample-campus.ts: a Drizzle upsert, safe to rerun. Walkthrough: docs/fork-data-guide.md.

Class schedules are the recurring part. Room TBA pulls from AMIS, which is UPLB's system. You do not have AMIS, so flatten whatever export your registrar or SAIS equivalent gives you (CSV, JSON, a scraped portal, a PDF someone has to retype) into the documented shape of bun run import:classes-generic and rerun it each term. data/sample-campus/classes.csv is the worked example.

After you change the Drizzle schema at all, regenerate the offline cache schema so PGlite matches Postgres:

bun run generate:pglite-schema

Deploy

Import your fork into Vercel. Set these env vars in the project (Production and Preview):

• DATABASE_URL: your Supabase pooler URL.
• ADMIN_PASSWORD: same one you used locally.
• ADMIN_SESSION_SECRET: 32+ random chars, used to sign editor cookies.
• ISR_BYPASS_TOKEN: 32+ random chars, must match bypassToken in astro.config.mjs. Without it, editor publishes do not revalidate the SEO pages.
• PUBLIC_MAPTILER_KEY: your key.
• PUBLIC_APP_ENV=production on your production deploy; staging on preview.

Deploy. Push to your default branch and Vercel builds it. The build needs DATABASE_URL or prerendered pages 500.

The painful parts

• Class import is write-your-own. AMIS is UPLB-only. Your registrar's export is the long pole. Budget time for it.
• Map tiles cost money at scale. MapTiler free tier is fine for a campus with a few thousand users. If the whole student body hits it during enrollment, you may need a paid plan or a self-hosted tile server.
• The 3D terrain needs a DEM. If your campus is flat, set campusTerrain.enabled: false in campus.config.ts. No DEM, no 3D hills.
• Supabase free tier pauses after a week of no activity. Fine for a small campus. For high traffic, upgrade or self-host Postgres.
• You are maintaining a fork. Upstream moves. Rebase pain is real. Keep your campus-specific changes in the clearly UPLB-marked files above so merges do not stomp your data config.
• The wiki page you are reading is UPLB-specific too. Replace it with your own campus guide, or delete it.

License and credit

Application code is MIT. Keep the LICENSE file. You can run a fork for your campus, sell hosting around it, teach with it. You do not have to ask.

The UPLB database contents are not a MIT dump you can ship unchanged. Replace campus rows with your own. Community-curated map entities in upstream Room TBA are CC-BY 4.0; if you reuse those entities, credit Room TBA / UPLB Tools. OpenStreetMap data stays ODbL. AMIS and other university imports are not open bulk data.

Credit is free. The README credits the people who built this. Do not strip those names and pass the work off as yours. If your fork takes off, a line back to uplbtools/room-tba is good manners.