Skip to content

About

Independent campus project – THD Room Finder. Find free study rooms using THabella data. Community fork of arudaev/THD-Room-Finder; no course assignment.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

440 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

THD Room Finder – a hand-drawn banner: the THD campus from above and a phone showing the same map

THD Room Finder

Find a free study room at Technische Hochschule Deggendorf – and know how long it stays free.

Vite + React TypeScript Capacitor Android PWA GPL-3.0


Get the App


Overview

THD Room Finder queries THD's public scheduling system THabella and cross-references occupied rooms against the rooms that actually host teaching, to show which classrooms are free right now – or at any time you pick.

v2 is a single React + TypeScript codebase that runs as an installable PWA on the web and, via Capacitor, as a native Android app. (It replaces the v1 native Android + native iOS + vanilla-JS PWA – all preserved under the v1-native git tag.)

No accounts. No backend. No configuration. Just open the app and find a room.

The v2 redesign sharpens one question – "where can I sit, right now, for as long as I need?":

  • Duration-first. Every room leads with how long it stays free (free 2h 10m / free all day), not just a binary empty/occupied.
  • Three-state status. free (teal) · closing-soon (amber) · occupied (red).
  • Answer, not a database. The big free-room count flows into a list ranked longest-free first, narrowed by building.
  • Only real study rooms. A room appears only if it hosts a lecture this week – offices and always-closed spaces (and sports/outdoor venues) drop out.

Features

  • Free-room finder – duration-ranked list of rooms free at the query time
  • Room search – find any teaching room by code, name or equipment, with live status, even when it's busy; bilingual (searching "projector" finds "Beamer")
  • Building filter – the primary way to narrow, once distance is off the table
  • Time-travel lookup – check availability at any future date/time
  • Plan-ahead when closed – before the doors open, preview the rooms that will be free instead of a dead-end "closed" notice
  • Room detail – status banner, capacity, facilities, contact, the day's schedule
  • Campus map – free rooms on a 2.5D campus map, with amenity badges for dining (Mensa, cafés) and study/library spaces
  • Saved rooms – star your usual spot; Profile answers "free right now?"
  • Focus sessions – start focus in a free room, in rhythms of blocks and breaks; Private claims the room anonymously, Public invites your batch
  • Focus at home – the same rhythm without a room, from the Focus tab; only you see it, and it counts in your focus graph
  • Session sounds – coffee pours for a break, bright dings call you back; pick a set for home and for campus, on Android even with the phone locked
  • Study profile – sign in with an email code and pick your programme from the THD programme list; you appear as e.g. AIN 7
  • Focus graph – your semester on Profile, built on the device, shareable as a link
  • Study tables – set a table in a free room, share one link, start together
  • Student groups – registered groups host gatherings people reply to
  • Works through outages – if THabella is down, rooms stay listed as "availability unknown" and focus still starts
  • Bilingual – English UI with German preserved; live EN/DE toggle
  • Adaptive navigation – bottom bar (phone) → rail (tablet) → drawer (desktop)
  • Dark theme – follows the device, with a manual override
  • Offline-friendly PWA – installable, cached last data, 5-minute auto-refresh

Tech Stack

Language TypeScript (strict)
UI React 18 + a Material 3 design system (CSS-variable tokens)
Routing React Router
Build Vite + vite-plugin-pwa (Workbox service worker)
Native Capacitor (Android; iOS deferred until funding)
Networking Web → same-origin Vercel proxy (api/); Android → THabella direct via Capacitor HTTP
Tests Vitest
Web host Vercel (Frankfurt functions)

The visual system (tokens + components) is sourced from the Claude Design project THD Room Finder Design System, mirrored in design/system/, and implemented in src/styles/tokens and src/components.


Architecture

UI (React screens, src/features/*)
  └── Design system (src/components/*  – ported Material 3 components)
  └── State (React context: RoomData, Favorites, I18n, Theme)
        └── Domain (src/domain/*  – framework-free, unit-tested)
              parse · availability (duration/status/ranking) · teaching-room filter · priority
        └── Data (src/data/*)
              thabellaClient (web proxy / native HTTP) · mappers · localStorage cache

The domain layer is a faithful TypeScript port of the v1 Android app's trusted THabella logic (RoomMapper, PeriodMapper, GetFreeRoomsUseCase, RoomPriorityPolicy), extended with duration/status derivation and the teaching-room filter. See the architecture overview and AGENTS.md for a fuller map.


THabella API

Full reference: docs/architecture/thabella-api.md.

Base URL: https://thabella.th-deg.de/thabella/opn/ – no auth required.

Endpoint Body Purpose
POST /room/findRooms {} All rooms as RoomDto[]
POST /period/findByDate/{dateTime} {"sqlDate":"YYYY-MM-DD HH:mm"} A day's events as PeriodDto[]

The API is undocumented and may change without notice – DTOs are fully nullable and unknown keys are ignored. On the web these go through the caching proxy in api/; on Android the app calls THabella directly. The teaching-room set is built from a week of these queries (Mon–Fri), cached 24h.


Build & Run

Requires Node 22.12+.

npm install
npm run dev        # dev server at http://localhost:5173 (proxies THabella)
npm run build      # typecheck + production build to dist/
npm run preview    # serve the production build
npm test           # Vitest domain/data tests
npm run typecheck  # tsc --noEmit

Android (Capacitor)

# Regenerate launcher/splash assets from assets/logo.svg when branding changes:
npm run assets:android
npm run build
npx cap sync android
cd android && ./gradlew assembleDebug      # debug APK
# Signed release: fill android/keystore.properties (see the .example), then:
./gradlew assembleRelease
# → android/app/build/outputs/apk/release/app-release.apk (sideload on Android 12+)

iOS is intentionally not scaffolded yet (blocked on Apple developer funding); the data layer already abstracts native vs web HTTP, so npx cap add ios later is an isolated step.


CI / Delivery

Workflow Trigger What it does
ci.yml push / PR Typecheck, test, web build; build Android debug APK
pr-conventions.yml PR Conventional title, linked issue, auto-assign, path labels
issue-commands.yml issue comment /take and /drop self-assignment
release.yml tag v* Build web + signed Android APK, publish a GitHub release
pages.yml push to main Deploy website/ marketing page to GitHub Pages

The web app deploys on Vercel (build dist/ + api/ functions). Signing material is never committed: keep release.keystore locally, and CI recreates it from a KEYSTORE_BASE64 secret plus KEYSTORE_PASSWORD / KEY_ALIAS / KEY_PASSWORD.


Repository Structure

src/            React app – domain/ data/ components/ features/ i18n/ lib/ styles/
api/            Vercel serverless proxy for THabella (rooms.js, periods.js)
android/        Capacitor Android project (generated)
public/icons/   App icons (PWA + Android)
shared/         Canonical room/building taxonomy (JSON)
website/        Static marketing landing page (GitHub Pages)
scripts/dev/    Python helpers (taxonomy normalization, THabella snapshot)
docs/           Documentation: product, architecture, development, contributing
design/         Mirror of the Claude Design system + design brief

License

GPL-3.0 — see LICENSE.

Roadmap

Room Finder grew from an exam-season utility into a daily focus tool: walk into a free room, press Start focus, and study privately or with your batch. Next is a measured pilot with student batches, then the city layer.

Phase Milestone Status
Foundation Design system, docs, board and automation Done
Phase 1 Focus sessions: private claims, batch sessions, Profile tab, focus graph Shipped (v2.3); end-to-end verification open
Phase 1 Focus at home, the Focus tab and session sounds Shipped (v2.6)
Phase 2 Study tables; student groups and gatherings Shipped (v2.5)
Phase 3 City layer: Deggendorf events, festivals and museums Later

Read the charter, the focus sessions spec and the roadmap, or follow progress on the project board.

Documentation

All documentation lives in docs/: product, architecture, development and contributor guides. The design system is mirrored in design/ and lives in Claude Design.

Contributing

Questions, ideas and feedback are welcome in Discussions. See the roadmap for where the app is heading.

Pick an issue in the Ready column of the project board, comment /take, and open a draft PR. Start with CONTRIBUTING.md; look for good first issue.

About

Independent campus project – THD Room Finder. Find free study rooms using THabella data. Community fork of arudaev/THD-Room-Finder; no course assignment.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages