# sparshkapoor-coder/campusloop architecture

> Architecture diagram of the GitHub repository sparshkapoor-coder/campusloop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sparshkapoor-coder/campusloop
- Repository: https://github.com/sparshkapoor-coder/campusloop

## Overview

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: [`lib/main.dart`](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/main.dart) (App start), [`lib/recommendation_engine.dart`](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/recommendation_engine.dart) (Recommend), [`lib/home_screen.dart`](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/home_screen.dart) (Home), [`lib/registration_screen.dart`](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/registration_screen.dart) (Register)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Flutter client"]
  node_main["App start<br/>Flutter entry<br/>[main.dart]"]
  node_theme["Theme<br/>[theme.dart]"]
  node_registration["Register<br/>screen"]
  node_home["Home<br/>screen<br/>[home_screen.dart]"]
  node_timetable["Timetable<br/>screen"]
  node_chat["Chat<br/>screen<br/>[chat_screen.dart]"]
  node_profile["Profile<br/>screen"]
  node_credit["About<br/>ui"]
end

subgraph group_domain["Campus domain"]
  node_campus_data[("Campus data<br/>campus model<br/>[campus_data.dart]")]
  node_hostel_data[("Hostels<br/>campus model<br/>[hostel_data.dart]")]
  node_slot_data[("Slots<br/>schedule model<br/>[slot_data.dart]")]
  node_recommendation{{"Recommend<br/>logic engine"}}
end

subgraph group_backend["Backend boundary"]
  node_firebase_options["Firebase opts<br/>config"]
  node_groq_service{{"Groq proxy<br/>AI client<br/>[groq_service.dart]"}}
  node_functions["Cloud Worker<br/>serverless proxy<br/>[index.js]"]
end

subgraph group_platform["Platform shells"]
  node_android_main["Android host<br/>native shell<br/>[MainActivity.kt]"]
  node_ios_app["iOS host<br/>native shell<br/>[AppDelegate.swift]"]
  node_web_index["Web host<br/>web shell<br/>[index.html]"]
  node_tests["Widget test<br/>[widget_test.dart]"]
end

node_main -->|"uses"| node_theme
node_main -->|"routes to"| node_registration
node_main -->|"routes to"| node_home
node_main -->|"routes to"| node_timetable
node_main -->|"routes to"| node_chat
node_main -->|"routes to"| node_profile
node_main -->|"opens"| node_credit
node_home -->|"reads"| node_recommendation
node_timetable -->|"uses"| node_slot_data
node_registration -->|"selects"| node_hostel_data
node_home -->|"reads"| node_campus_data
node_recommendation -->|"reads"| node_campus_data
node_recommendation -->|"reads"| node_hostel_data
node_recommendation -->|"reads"| node_slot_data
node_chat -->|"calls"| node_groq_service
node_groq_service -->|"proxies via"| node_functions
node_main -->|"initializes"| node_firebase_options
node_functions -.->|"integrates with"| node_firebase_options
node_android_main -->|"hosts"| node_main
node_ios_app -->|"hosts"| node_main
node_web_index -->|"hosts"| node_main
node_tests -.->|"verifies"| node_main

click node_main "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/main.dart"
click node_theme "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/theme.dart"
click node_registration "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/registration_screen.dart"
click node_home "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/home_screen.dart"
click node_timetable "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/timetable_entry_screen.dart"
click node_chat "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/chat_screen.dart"
click node_profile "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/profile_screen.dart"
click node_credit "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/made_by_credit.dart"
click node_campus_data "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/campus_data.dart"
click node_hostel_data "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/hostel_data.dart"
click node_slot_data "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/slot_data.dart"
click node_recommendation "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/recommendation_engine.dart"
click node_firebase_options "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/firebase_options.dart"
click node_groq_service "https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/groq_service.dart"
click node_functions "https://github.com/sparshkapoor-coder/campusloop/blob/main/functions/index.js"
click node_android_main "https://github.com/sparshkapoor-coder/campusloop/blob/main/android/app/src/main/kotlin/com/example/campusloop/MainActivity.kt"
click node_ios_app "https://github.com/sparshkapoor-coder/campusloop/blob/main/ios/Runner/AppDelegate.swift"
click node_web_index "https://github.com/sparshkapoor-coder/campusloop/blob/main/web/index.html"
click node_tests "https://github.com/sparshkapoor-coder/campusloop/blob/main/test/widget_test.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_theme,node_registration,node_home,node_timetable,node_chat,node_profile,node_credit toneBlue
class node_campus_data,node_hostel_data,node_slot_data,node_recommendation toneAmber
class node_firebase_options,node_groq_service,node_functions toneMint
class node_android_main,node_ios_app,node_web_index,node_tests toneRose
```

## Components

### Flutter client

Primary mobile UI and app flow

- [App start](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/main.dart): Flutter entry · Bootstraps the app and routing · `lib/main.dart`
- [Theme](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/theme.dart): UI theme · Shared styling and color system · `lib/theme.dart`
- [Register](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/registration_screen.dart): screen · First-run profile onboarding · `lib/registration_screen.dart`
- [Home](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/home_screen.dart): screen · Next-class dashboard and recommendations · `lib/home_screen.dart`
- [Timetable](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/timetable_entry_screen.dart): screen · FFCS-style schedule entry · `lib/timetable_entry_screen.dart`
- [Chat](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/chat_screen.dart): screen · Campus AI assistant UI · `lib/chat_screen.dart`
- [Profile](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/profile_screen.dart): screen · Profile and quick timetable access · `lib/profile_screen.dart`
- [About](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/made_by_credit.dart): ui · Lightweight attribution screen · `lib/made_by_credit.dart`

### Campus domain

Hardcoded campus model and schedule logic

- [Campus data](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/campus_data.dart): campus model · Buildings, locations, canteens, timings · `lib/campus_data.dart`
- [Hostels](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/hostel_data.dart): campus model · Hostel blocks and related metadata · `lib/hostel_data.dart`
- [Slots](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/slot_data.dart): schedule model · Class slot grid and timetable structure · `lib/slot_data.dart`
- [Recommend](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/recommendation_engine.dart): logic engine · Computes action from schedule, location, and time windows · `lib/recommendation_engine.dart`

### Backend boundary

Firebase persistence and proxied AI access

- [Firebase opts](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/firebase_options.dart): config · Firebase app configuration generated for Flutter · `lib/firebase_options.dart`
- [Groq proxy](https://github.com/sparshkapoor-coder/campusloop/blob/main/lib/groq_service.dart): AI client · Chat integration through a proxy boundary · `lib/groq_service.dart`
- [Cloud Worker](https://github.com/sparshkapoor-coder/campusloop/blob/main/functions/index.js): serverless proxy · Node.js backend workspace for proxy and server logic · `functions/index.js`

### Platform shells

Native and web targets generated by Flutter

- [Android host](https://github.com/sparshkapoor-coder/campusloop/blob/main/android/app/src/main/kotlin/com/example/campusloop/MainActivity.kt): native shell · Android bootstrap and embedding · `android/app/src/main/kotlin/com/example/campusloop/MainActivity.kt`
- [iOS host](https://github.com/sparshkapoor-coder/campusloop/blob/main/ios/Runner/AppDelegate.swift): native shell · iOS app entry and lifecycle integration · `ios/Runner/AppDelegate.swift`
- [Web host](https://github.com/sparshkapoor-coder/campusloop/blob/main/web/index.html): web shell · Web bootstrap entry for Flutter web · `web/index.html`
- [Widget test](https://github.com/sparshkapoor-coder/campusloop/blob/main/test/widget_test.dart): test · Basic Flutter UI verification · `test/widget_test.dart`

## Connections

- 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
