How sparshkapoor-coder/campusloop works
1. High-level shape
CampusLoop is a Flutter client app with a mostly client-side architecture. The app runs on Android/iOS and also has generated desktop/web targets, but the core product is a mobile campus companion for VIT Bhopal students.
2. Primary client entry point
The Flutter app starts in lib/main.dart, with shared styling in lib/theme.dart. The main user-facing areas are split into separate screens: registration, home dashboard, timetable entry, chat, and profile. This keeps the UI bounded into a few clear domains rather than one large monolith.
3. Core UI subsystems
- registration_screen.dart: first-run onboarding for name, gender, and hostel block.
- home_screen.dart: the “next class + recommendation” dashboard.
- timetable_entry_screen.dart: FFCS-style schedule builder using slot selection.
- chat_screen.dart: campus-scoped AI assistant.
- profile_screen.dart: user profile and quick access to timetable editing.
- made_by_credit.dart: lightweight attribution/about UI.
4. Campus domain data is hardcoded and campus-specific
The files campus_data.dart, hostel_data.dart, and slot_data.dart contain the fixed VIT Bhopal campus model: buildings, hostels, canteens, and the slot grid. These files are part of the app’s domain layer and are the reason the app is currently tied to one campus unless those datasets are replaced.
5. User state and persistence
The app uses Firebase Anonymous Authentication so each device gets a persistent user identity without login. Student-specific data is stored under students/{uid} in Firestore, including profile details, timetable entries, and cancellations. That makes the backend boundary straightforward: one authenticated user document tree per device/user.
6. Firestore-backed data model
The architecture separates:
- Private per-student data: profile, timetable, cancellations
- Read-only campus data: locations, precomputed walking times, mess timings
This separation is important for the diagram: the client can read campus-wide references but only writes into its own student subtree.
7. Recommendation engine flow
recommendation_engine.dart is the key business-logic subsystem. It combines:
- the student’s upcoming timetable
- the day’s cancelled classes
- hostel location
- campus walking times from the distance matrix
- mess timings and meal buffers
The output is a recommendation such as “go to mess,” “canteen works,” or “stay put.” The important architectural point is that the recommendation is computed from schedule + location + time windows, not just timetable gaps.
8. Campus geometry and time estimation
The README describes a one-time offline seeding process that populates campusLocations and distanceMatrix. Walking times are precomputed using Google Maps Distance Matrix API and then stored in Firestore. At runtime, the app does not call Google Maps; it reads the saved matrix. That keeps the client lightweight and avoids live routing dependencies.
9. AI chat boundary
groq_service.dart handles the chat integration. The app does not call Groq directly; it sends requests to a Cloudflare Worker proxy, which verifies the Firebase session before forwarding to Groq. This creates a clear security boundary: the mobile app never contains the Groq API key, and campus-specific chat is grounded in the same student/campus data model used elsewhere.
10. Backend and serverless pieces
The repo includes a functions/ workspace with Node.js tooling, plus Firebase configuration files (firebase.json, .firebaserc), but the README’s production architecture centers on Firestore plus an external Worker proxy. In other words, the app’s backend responsibilities are intentionally minimal and split between Firebase storage/auth and a small serverless proxy layer for AI calls.
11. Platform scaffolding
The android/, ios/, web/, macos/, linux/, and windows/ directories are standard Flutter platform shells. They mainly support packaging, launch icons, manifests, and native bootstrapping; they do not introduce separate product logic beyond the Flutter app itself.
12. Verification and tooling
There is a basic Flutter test entry point in test/widget_test.dart, plus lint configuration in analysis_options.yaml. These support app quality, but the architecture is dominated by the Flutter client, Firestore persistence, offline-seeded campus data, and the proxied Groq chat service.
Main entry points: main.dart App start · recommendation_engine.dart Recommend · home_screen.dart Home · registration_screen.dart Register
Components 19
Flutter client
Primary mobile UI and app flow
- App start · Bootstraps the app and routing
lib/main.dart - Theme · Shared styling and color system
lib/theme.dart - Register · First-run profile onboarding
lib/registration_screen.dart - Home · Next-class dashboard and recommendations
lib/home_screen.dart - Timetable · FFCS-style schedule entry
lib/timetable_entry_screen.dart - Chat · Campus AI assistant UI
lib/chat_screen.dart - Profile · Profile and quick timetable access
lib/profile_screen.dart - About · Lightweight attribution screen
lib/made_by_credit.dart
Campus domain
Hardcoded campus model and schedule logic
- Campus data · Buildings, locations, canteens, timings
lib/campus_data.dart - Hostels · Hostel blocks and related metadata
lib/hostel_data.dart - Slots · Class slot grid and timetable structure
lib/slot_data.dart - Recommend · Computes action from schedule, location, and time windows
lib/recommendation_engine.dart
Backend boundary
Firebase persistence and proxied AI access
- Firebase opts · Firebase app configuration generated for Flutter
lib/firebase_options.dart - Groq proxy · Chat integration through a proxy boundary
lib/groq_service.dart - Cloud Worker · Node.js backend workspace for proxy and server logic
functions/index.js
Platform shells
Native and web targets generated by Flutter
- Android host · Android bootstrap and embedding
android/app/src/main/kotlin/com/example/campusloop/MainActivity.kt - iOS host · iOS app entry and lifecycle integration
ios/Runner/AppDelegate.swift - Web host · Web bootstrap entry for Flutter web
web/index.html - Widget test · Basic Flutter UI verification
test/widget_test.dart
Connections 22
- App start → Theme: uses · Applies shared app styling
- App start → Register: routes to · Entry flow for new users
- App start → Home: routes to · Primary dashboard
- App start → Timetable: routes to · Schedule editor flow
- App start → Chat: routes to · AI assistant entry
- App start → Profile: routes to · User profile flow
- App start → About: opens · About/attribution page
- Home → Recommend: reads · Displays computed guidance
- Timetable → Slots: uses · Builds schedule from slot grid
- Register → Hostels: selects · Captures hostel block
- Home → Campus data: reads · Uses campus locations and timings
- Recommend → Campus data: reads · Uses campus geometry and meal timings
- Recommend → Hostels: reads · Uses hostel location as anchor
- Recommend → Slots: reads · Uses upcoming class schedule
- Chat → Groq proxy: calls · Sends chat requests through service layer
- Groq proxy → Cloud Worker: proxies via · Backend verification and forwarding boundary
- App start → Firebase opts: initializes · Connects Flutter app to Firebase
- Cloud Worker → Firebase opts: integrates with · Shares Firebase-backed auth and data boundary
- Android host → App start: hosts · Android runtime shell
- iOS host → App start: hosts · iOS runtime shell
- Web host → App start: hosts · Web runtime shell
- Widget test → App start: verifies · Basic app widget coverage