Unser Stundenplan: A Family Timetable Viewer

When you have school-age children, keeping track of their daily schedules can be a challenge. Between multiple kids, changing timetables, last-minute cancellations, and the occasional holiday, it’s hard to know who needs to be where and when. That’s why I built Unser Stundenplan—a simple web application designed to be mounted on a kitchen iPad, showing the family’s school schedules at a glance.

It’s been in production for over a year now, and it’s made mornings considerably smoother for us. After seeing how well it works, I decided to publicly host an instance for anyone to use and release the project as open-source.

What is it?

Unser Stundenplan (German for “Our Timetable”) is a web application that fetches and displays timetables from the Beste Schule school management system. It’s specifically designed for German-speaking families whose schools use the Beste Schule platform.

The tool automatically shows the next school day’s schedule and intelligently handles weekends and holidays. It refreshes periodically to catch any last-minute changes—like cancelled lessons or room changes that teachers might update throughout the day.

Key features

Smart date handling: The app doesn’t just show today’s schedule. It looks ahead to find the next actual school day, skipping weekends and holidays automatically. If there are more than 5 days off ahead, it switches to a special holiday mode. This mode displays a countdown to the next school day.

Multi-child support: If you have multiple children in different classes, the app displays their schedules side-by-side in a clean table format, making it easy to see the whole family’s day at once.

Auto-refresh: The timetable updates every few minutes to catch schedule changes, and the entire page reloads every 6 hours to ensure you’re running the latest version of the app.

Cancelled lessons: When a teacher cancels a lesson, it appears struck through in the schedule, so kids immediately know what’s different.

Daily notes: Important announcements from the school (from the substitution plan) are displayed below the timetable.

iOS optimized: The app works great as a fullscreen web app on iOS Safari, perfect for an iPad in guided access mode.

Try it yourself

If your school uses the Beste Schule platform, you can try Unser Stundenplan right now.

Just:

1. Sign in to the Beste Schule website (note: the website, not the mobile app)
2. Navigate to your passport page
3. Create a new “Personal Access Token”
4. Open Unser Stundenplan and enter the token when prompted

For the best experience:

• Use an old iPad and mount it in your hallway or kitchen (Make sure it is connected to power)
• Open the app in Safari and add it to the home screen (so you get fullscreen mode)
• Enable “Guided Access” to prevent accidental exits
• The display will auto-refresh and show upcoming schedules automatically

Implementation

Unser Stundenplan is built as a frontend-only application with no server-side components. All API calls are made directly from the browser to the Beste Schule API using a personal access token that users generate from their school account.

The tech stack is simple and consists of: TypeScript, React 18, Vite, and Biome. The entire codebase is just a handful of files totaling under a thousand lines of code.

How it works

The core logic lives in the getTimeTables() function in api.ts. When called with a start date, it:

1. Searches for the next school day. Starting from the given date, it checks up to 50 days ahead, skipping weekends automatically
2. Fetches week data. Uses the Beste Schule API’s week journal endpoint with a smart caching mechanism to avoid redundant API calls
3. Processes lessons. Groups lessons by class level, determines class names from common prefixes in group IDs, and builds a unified timetable structure
4. Tracks days off. Calculates how many days (including weekends) are between today and the next school day

The App component then takes this data and renders it into a clean, readable table. The UI shows:

• The date and weekday of the schedule
• Hour numbers with time ranges
• Subject names, teacher names, and room numbers for each lesson
• Visual indicators for cancelled lessons
• Any important notes from the school

Special touches

Holiday mode: When there are 5 or more days until the next school day, the app switches to a special holiday mode. The background changes to a colorful rainbow, and instead of a timetable, it displays “FERIEN!” (holidays!) in large text with a countdown.

Wake lock: The app uses the Screen Wake Lock API to prevent the iPad screen from turning off while the timetable is displayed—perfect for a kitchen display that should always be visible.

Token storage: Your Beste Schule API token is stored securely in the browser’s localStorage, so you only need to enter it once per device.

Deployment

The application is deployed on Vercel with completely automated CI/CD. When pushing to the main branch, Vercel automatically detects the Vite configuration, builds the app, and deploys it. No configuration files needed—the platform recognizes the standard Vite setup from package.json.

Since this is a static frontend app with no backend, you could also host it on any static hosting service like GitHub Pages, Netlify, or even just serve the build output from a simple web server.

The bilingual paradox

One quirky aspect of this project is its bilingual nature: the codebase, commit messages, and pull requests are all in English (following international coding conventions), while the user interface is strictly in German—reflecting the fact that the tool is built for German students and families using German school systems.

More information

The source code is available on GitHub for anyone interested in the implementation details or wanting to adapt it for their own needs.