Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Building Data Codebook

Field-by-field reference for apps/frontend/src/data/buildingTypes.ts, buildings.json, and tags.tsx. The app reads buildings from the database through the API, not from the JSON files (see Data loading).

Building data tree

Where to find each piece of information on an exported Building object:

Building
├─ id                  string
├─ name                string
├─ media
│  ├─ mainImage        string
│  ├─ icon?            string
│  ├─ photos[]
│  │  ├─ link          string
│  │  └─ description   string
│  └─ floorPlans[]
│     ├─ link              string
│     ├─ description       string
│     ├─ category          "roomType" | "floor"
│     └─ virtualTourLink?  string
├─ amenities
│  ├─ roomTypes        RoomType[]
│  ├─ bathrooms
│  │  ├─ types         BathroomType[]
│  │  └─ details?      string
│  ├─ ac
│  │  ├─ level         ACLevel
│  │  └─ details?      string
│  ├─ kitchen
│  │  ├─ scope         KitchenScope
│  │  └─ details?      string
│  ├─ laundry
│  │  ├─ location      LaundryLocation
│  │  └─ details?      string
│  ├─ commonAreas
│  │  ├─ hasLounge     boolean
│  │  └─ details?      string
│  ├─ gym
│  │  ├─ available     boolean
│  │  └─ details?      string
│  └─ genderHousing    GenderHousing
├─ accessibility
│  ├─ wheelchairAccessible   boolean
│  ├─ serviceAnimalFriendly  boolean
│  ├─ groundFloorRooms       boolean
│  └─ strobeAlarm            boolean
├─ location
│  ├─ latitude?        number
│  ├─ longitude?       number
│  ├─ closeBuildings[] string (campus building ids)
│  └─ note?            string
├─ editorialTags?[]    string
└─ reviews             (added by the API, not in buildings.json)
   ├─ count            number
   └─ averages
      ├─ overall       number | null
      ├─ amenities     number | null
      ├─ roomQuality   number | null
      └─ noise         number | null

reviews is the average rating (1-5) for each review question and how many students answered. An average is null while the building has no reviews. Older reviews can lack a value for some questions, so count can be higher than the number of ratings behind an average. It refreshes when the building data is loaded again, which the review form does after a review is saved.

Enums

All enums below are string enums. The Value column is the string stored in buildings.json, returned by the enum at runtime, and used as the label of the Postgres enum of the same name in the dorm table (see database-schema.md). Keep the three in sync when adding a member.

RoomType

ValueMemberMeaning
trad_singleTradSingleTraditional-style single, shared hallway bathroom.
trad_doubleTradDoubleTraditional-style double, shared hallway bathroom.
trad_tripleTradTripleTraditional-style triple, shared hallway bathroom.
semi_suite_singleSemiSuiteSingleSemi-suite single, bathroom shared with an adjacent suite.
semi_suite_doubleSemiSuiteDoubleSemi-suite double, bathroom shared with an adjacent suite.
semi_suite_tripleSemiSuiteTripleSemi-suite triple, bathroom shared with an adjacent suite.
semi_suite_double_as_tripleSemiSuiteDoubleAsTripleSemi-suite double that can house three occupants.
semi_suite_quadSemiSuiteQuadSemi-suite, four occupants.
apartment_tripleApartmentTripleApartment-style triple.
studio_apartment_singleStudioApartmentSingleStudio apartment, single occupant.
studio_apartment_doubleStudioApartmentDoubleStudio apartment, two occupants.
studio_apartment_tripleStudioApartmentTripleStudio apartment, three occupants.

BathroomType

ValueMemberMeaning
communalCommunalShared per floor/wing, traditional style.
shared_suiteSharedSuiteShared with one adjacent suite, semi-suite style.
privatePrivateTruly en-suite / in-room, apartment style only.

ACLevel

ValueMemberMeaning
noneNoneNo AC.
by_necessityByNecessityAccommodation, triple, or lottery-only AC.
windowWindowWindow units, not central.
centralCentralFull central AC.

LaundryLocation

ValueMemberMeaning
noneNoneNo laundry.
basementBasementBasement only.
each_floorEachFloorLaundry on every floor.
in_unitInUnitIn-unit washer/dryer.

KitchenScope

ValueMemberMeaning
noneNoneNo kitchen access.
sharedSharedCommunal, building or floor level; details says which.
in_unitInUnitKitchenette in the room (“en suite kitchen”).

Floor-vs-building distinctions for Shared live in the details string, not as a separate enum value.

GenderHousing

ValueMemberMeaning
co_edCoEdCo-ed housing.
women_onlyWomenOnlyWomen only.
men_onlyMenOnlyMen only.
gender_inclusiveGenderInclusiveGender-inclusive housing.

“Value + details” wrapper pattern

Bathrooms, AirConditioning, Kitchen, Laundry, CommonAreas, Gym all follow one pattern: a comparable/filterable value (enum, array, or boolean) plus an optional details string for a freeform human blurb. Every attribute that needs to be both compared and described gets this shape.

  • Bathrooms.types is an array so a building with more than one bathroom style lists all of them.
  • CommonAreas.hasLounge backs the “Common areas” filter.
  • Gym.available is a plain boolean for filtering; details carries the description.
  • details should add what the value can’t say (for example which floors share a bathroom), not restate it. The AC and kitchen cards show details in place of the value’s label, so a details string there should still name the value.

Grouped types

  • AmenityData holds everything the filter/survey/comparison UI reads: room types, bathrooms, AC, kitchen, laundry, common areas, gym, gender housing.
  • Accessibility holds wheelchairAccessible, serviceAnimalFriendly, groundFloorRooms, strobeAlarm (strobe fire alarm & doorbell). Filled in per building as data becomes available.
  • Location holds latitude/longitude for a “distance from landmark” filter (no distance value is stored on the building itself), closeBuildings (ids of the four nearest academic or non-residential campus buildings, nearest first, for the “Closest Buildings” detail card; they are listed in campusBuildings.json, not in buildings.json), and an optional note for a human-written blurb.
  • CampusBuilding is id + code (short label shown on the map marker) + name + optional subtitle (department or function, shown under the name in the map’s origin picker) + latitude + longitude, one per academic or non-residential building in campusBuildings.json (plus Resnik, which is also a food hall). It feeds the “Distance from” filter options and the closeBuildings ids; add a row there to offer a new landmark.
  • GalleryImage is link + description, one per photo.
  • FloorPlan is link + description + category ("roomType" | "floor") + optional virtualTourLink, which points to a walkthrough for that specific floor plan.
  • Media holds mainImage, optional icon, photos[], and floorPlans[].
  • Building is the top-level shape: id, code (short label for map markers and cards; unique across housing and campus buildings), name, media, amenities, accessibility, location, and optional editorialTags for hand-authored tags with no structured source.

Filter scoring

scoreBuilding in scoring.ts scores a building against the filter panel. Set controls add points; missing data adds nothing and never subtracts:

Filter controlScored from
Air conditioningamenities.ac.level is Window or Central
Laundry on each flooramenities.laundry.location is EachFloor
En suite bathroomamenities.bathrooms.types has SharedSuite or Private
En suite kitchenamenities.kitchen.scope is InUnit
Single roomamenities.roomTypes has a single-occupant type
Service Animalaccessibility.serviceAnimalFriendly
Wheelchair accessibleaccessibility.wheelchairAccessible
Experience Ratings, Building Ratings (Overall Experience, Amenities, Quietness, Room Quality, Bathroom Quality, Common Space Quality)reviews.averages, as a minimum: at or above the chosen value scores 2 points, each point below takes 1 away, down to 0
Distance fromstraight-line distance from the dorm’s coordinates to the chosen campus building in campusBuildings.json; full points at 0 m, fading to 0 at 800 m

Buildings with no ratings, or with empty accessibility flags, score 0 for those controls. groupBuildings sorts by score into bestFit, decentFit, and wildCard, three per row.

Tag derivation

deriveTags(building) in tags.tsx computes a building’s tag ids from its structured fields, so a tag can never drift out of sync with the data it is based on:

Tag idDerived from
noKitchenamenities.kitchen.scope === KitchenScope.None
limitedACamenities.ac.level === ACLevel.ByNecessity
noCentralACamenities.ac.level is neither None nor Central
gymAccessamenities.gym.available
girlsOnlyamenities.genderHousing === GenderHousing.WomenOnly
lgbtqInclusiveamenities.genderHousing === GenderHousing.GenderInclusive

editorialTags on a building are appended as-is, for a tag with no structured backing.

Data loading

Buildings and campus buildings come from the database, not from the JSON files. GET /api/buildings and GET /api/campus-buildings return them in the shapes above. hooks/useBuildingData.ts fetches both once when the app opens, data/apiBuildings.ts turns the response into Building[] (checking each enum string against the enums in buildingTypes.ts and throwing on one it does not know), and BuildingContext hands the result to components through useBuildings() and useCampusBuildings(). Pages other than the launch page wait for that load (BuildingGate). buildingTypes.ts holds every type and enum above, and is the single import source for the context, filter, survey, and comparison consumers.

buildings.json and campusBuildings.json are now seed data for deno task db:seed and fixtures for the tests in data/. To change a building, edit the JSON and re-run the seed. A new database gets the initial rows from migrations 0008_building_data and 0009_dorm_data; later edits need the seed or a new data migration.