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
| Value | Member | Meaning |
|---|---|---|
trad_single | TradSingle | Traditional-style single, shared hallway bathroom. |
trad_double | TradDouble | Traditional-style double, shared hallway bathroom. |
trad_triple | TradTriple | Traditional-style triple, shared hallway bathroom. |
semi_suite_single | SemiSuiteSingle | Semi-suite single, bathroom shared with an adjacent suite. |
semi_suite_double | SemiSuiteDouble | Semi-suite double, bathroom shared with an adjacent suite. |
semi_suite_triple | SemiSuiteTriple | Semi-suite triple, bathroom shared with an adjacent suite. |
semi_suite_double_as_triple | SemiSuiteDoubleAsTriple | Semi-suite double that can house three occupants. |
semi_suite_quad | SemiSuiteQuad | Semi-suite, four occupants. |
apartment_triple | ApartmentTriple | Apartment-style triple. |
studio_apartment_single | StudioApartmentSingle | Studio apartment, single occupant. |
studio_apartment_double | StudioApartmentDouble | Studio apartment, two occupants. |
studio_apartment_triple | StudioApartmentTriple | Studio apartment, three occupants. |
BathroomType
| Value | Member | Meaning |
|---|---|---|
communal | Communal | Shared per floor/wing, traditional style. |
shared_suite | SharedSuite | Shared with one adjacent suite, semi-suite style. |
private | Private | Truly en-suite / in-room, apartment style only. |
ACLevel
| Value | Member | Meaning |
|---|---|---|
none | None | No AC. |
by_necessity | ByNecessity | Accommodation, triple, or lottery-only AC. |
window | Window | Window units, not central. |
central | Central | Full central AC. |
LaundryLocation
| Value | Member | Meaning |
|---|---|---|
none | None | No laundry. |
basement | Basement | Basement only. |
each_floor | EachFloor | Laundry on every floor. |
in_unit | InUnit | In-unit washer/dryer. |
KitchenScope
| Value | Member | Meaning |
|---|---|---|
none | None | No kitchen access. |
shared | Shared | Communal, building or floor level; details says which. |
in_unit | InUnit | Kitchenette in the room (“en suite kitchen”). |
Floor-vs-building distinctions for Shared live in the details string, not as a separate enum value.
GenderHousing
| Value | Member | Meaning |
|---|---|---|
co_ed | CoEd | Co-ed housing. |
women_only | WomenOnly | Women only. |
men_only | MenOnly | Men only. |
gender_inclusive | GenderInclusive | Gender-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.typesis an array so a building with more than one bathroom style lists all of them.CommonAreas.hasLoungebacks the “Common areas” filter.Gym.availableis a plain boolean for filtering;detailscarries the description.detailsshould add what the value can’t say (for example which floors share a bathroom), not restate it. The AC and kitchen cards showdetailsin place of the value’s label, so adetailsstring there should still name the value.
Grouped types
AmenityDataholds everything the filter/survey/comparison UI reads: room types, bathrooms, AC, kitchen, laundry, common areas, gym, gender housing.AccessibilityholdswheelchairAccessible,serviceAnimalFriendly,groundFloorRooms,strobeAlarm(strobe fire alarm & doorbell). Filled in per building as data becomes available.Locationholdslatitude/longitudefor 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 incampusBuildings.json, not inbuildings.json), and an optionalnotefor a human-written blurb.CampusBuildingisid+code(short label shown on the map marker) +name+ optionalsubtitle(department or function, shown under the name in the map’s origin picker) +latitude+longitude, one per academic or non-residential building incampusBuildings.json(plus Resnik, which is also a food hall). It feeds the “Distance from” filter options and thecloseBuildingsids; add a row there to offer a new landmark.GalleryImageislink+description, one per photo.FloorPlanislink+description+category("roomType" | "floor") + optionalvirtualTourLink, which points to a walkthrough for that specific floor plan.MediaholdsmainImage, optionalicon,photos[], andfloorPlans[].Buildingis 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 optionaleditorialTagsfor 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 control | Scored from |
|---|---|
| Air conditioning | amenities.ac.level is Window or Central |
| Laundry on each floor | amenities.laundry.location is EachFloor |
| En suite bathroom | amenities.bathrooms.types has SharedSuite or Private |
| En suite kitchen | amenities.kitchen.scope is InUnit |
| Single room | amenities.roomTypes has a single-occupant type |
| Service Animal | accessibility.serviceAnimalFriendly |
| Wheelchair accessible | accessibility.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 from | straight-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 id | Derived from |
|---|---|
noKitchen | amenities.kitchen.scope === KitchenScope.None |
limitedAC | amenities.ac.level === ACLevel.ByNecessity |
noCentralAC | amenities.ac.level is neither None nor Central |
gymAccess | amenities.gym.available |
girlsOnly | amenities.genderHousing === GenderHousing.WomenOnly |
lgbtqInclusive | amenities.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.