Find a free study room at Technische Hochschule Deggendorf – and know how long it stays free.
- Use it now: thd-room-finder.vercel.app – no install needed, or "Add to Home Screen" for the PWA
- Android APK: latest release – sideload on Android 12+
- Landing page: arudaev.github.io/THD-Room-Finder
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.
- 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
| 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.
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.
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.
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# 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.
| 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.
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
GPL-3.0 — see LICENSE.
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.
All documentation lives in docs/: product, architecture,
development and contributor guides. The design system is mirrored in
design/ and lives in Claude Design.
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.
