System design slide

Inspiration

Every Hokie's first week starts the same way: download this app for dining, that one for buses, another for classes. Before long, your phone is full of apps that are buggy, outdated, and barely updated, and you still can't figure out how to get to your 9:05 on time.

As freshmen, we felt it right away. Several of us on the team are transfer students, and they told us the same thing: none of these apps helped them navigate a campus as big as Tech. When we dug through App Store reviews and Reddit threads, we saw we weren't alone. The problem wasn't a lack of apps. It was too many apps, none with a clear purpose.

So we built HokieFlow, one app for every Hokie and anyone finding their way around campus. Add your classes to your calendar, and HokieFlow builds your day around them, with the nearest transportation to each class, the closest dining halls, and more. Fewer apps, less storage, and directions that actually help.

HokieFlow turns your class schedule into a plan for your whole day. Add your classes and events to your calendar, and the app shows what's up next, how to get there, and where to grab food along the way, all in one place instead of five separate apps.

Key Features

Daily schedule: Add classes and events to your calendar, and HokieFlow keeps your day organized and shows what's coming up next.
Getting around: See Blacksburg Transit departures near you, and get walking or bus routes to any campus building that open in Apple Maps.
Dining, sorted by distance: Find the closest dining halls with one-tap directions.
Weather at a glance: Check conditions on the home screen to decide whether to walk or catch the bus.
GobblerConnect events: Campus events pulled in from GobblerConnect, so you can see current events without opening another app.
Ask HokieFlow: An AI campus assistant on every screen that answers questions in plain language
Google sign-in: We implemented the OAuth flow, callback, and sessions.
Made for you: Light and dark modes, class and event reminders, and an optional account to save your calendar between visits.

How we built it

HokieFlow is built without heavy frameworks. The frontend is plain HTML, CSS, and JavaScript, and the backend is a custom Python server using only the standard library. The frontend talks to the backend over a lightweight REST-style API, which keeps the app fast, easy to run, and free of a big dependency pile.

Data Pipeline

Frontend

HTML, CSS, and JavaScript: HTML structures the Home, Schedule, Dining, Bus, and Settings screens, CSS handles layout, colors, typography, and light/dark themes, and JavaScript handles navigation and schedule interactions.
GSAP + ScrollTrigger: Animate sections as users scroll.
Browser Geolocation API: Requests the user's location to find nearby dining and buses.
Fetch API: Connects the interface to our Python backend.
Apple Maps: Opens walking or transit directions in one tap.

Backend

Custom REST-style API: Built on Python's ThreadingHTTPServer, with routes like /api/time, /api/status, and /api/ask powering the clock, data freshness checks, and the AI assistant.
Accounts and sessions: Users, sessions, and saved schedules are stored in SQLite, so accounts work locally with no setup.
Optional cloud layer: Supabase (Postgres-backed) handles auth and Google cloud-backed accounts when we want to go beyond local storage.

APIs and Data Sources

Databricks: Spark Structured Streaming processes live Blacksburg Transit, weather, and dining data in real time, so the app stays current.
Blacksburg Transit: Live bus departures and routes.
VT Dining: Dining hall menus and hours.
National Weather Service: Current conditions for the home screen.
Campus events: Pulled from the campus events site by scraping its HTML, since there's no formal API.
Gemini API: Powers Ask HokieFlow, our AI campus assistant.

Challenges we ran into

Our biggest challenge was getting Google sign-in working. Because we built the backend on Python's standard library, we had no auth framework to lean on. We handled the OAuth flow, callback, state cookies, and session management ourselves, and every step had to line up, or login would quietly fail. On top of that, we had to keep accounts and saved schedules consistent between local SQLite and the optional Supabase layer.

Working with outside data was the second challenge. Blacksburg Transit, VT Dining, the weather service, and the Gemini API each returned data in a different shape, and the campus events site had no API at all, so we had to scrape it. This also limited our options for maps, since Apple Maps was the only one we could link successfully.

Finally, building in parallel caused merge conflicts in our auth and database code, since teammates were editing the same files. We had to slow down, agree on how those pieces fit together, and resolve them carefully.

Accomplishments that we're proud of

We're proud that HokieFlow puts schedule, buses, dining, and weather in one app instead of five. We were able to pull off most of what we originally envisioned, and we did it as a team.

Teamwork: We worked well as a group and solved every problem that came up, from sign-in bugs to merge conflicts.
Real-time data pipeline: Live campus data streamed through Databricks and Spark.
Real campus data: Live info from Blacksburg Transit, VT Dining, and the weather service
Ask HokieFlow: An AI assistant on every screen.
Google sign-in: Built from scratch, with no auth framework.
Clean design: Light and dark themes with smooth animations.

What we learned

We learned that connecting real data is harder than designing the screens. Every source worked differently, and one had no API at all. Building without frameworks taught us how servers and sign-in work under the hood, and working as a team taught us to plan for things breaking, such as merge conflicts and code errors. Most importantly, we learned that disagreeing as a team is okay, and it often led to better ideas and solutions!

What's next for HokieFlow

Next, we aim to make HokieFlow smoother, more accessible, and available to fellow Hokies. Our upcoming goals include:

Bug fixes and polish: Resolve remaining minor bugs to improve speed and reliability.
Open to students: Launch HokieFlow so that any Hokie can use it.
Easier navigation: Simplify how features are found and used.
Beyond Apple Maps: Support additional map options so that more students can use HokieFlow.
Accessibility-aware routing: Provide routes suited to students of all abilities, including those with disabilities.
Order Tracking: Know when food is ready, get accurate estimate of food wait times.