# b1tranger/b1t-sched architecture

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

- Interactive diagram: https://gitdiagram.com/b1tranger/b1t-sched
- Repository: https://github.com/b1tranger/b1t-sched

## Overview

1. **Overall shape**
   - This is a static, client-heavy single-page application. The runtime entry points are `index.html`, `js/app.js`, `sw.js`, and the CSS files under `css/`.
   - There is no visible build pipeline in the repo; the app appears to be served directly as HTML/CSS/JS, with Firebase providing the main backend services.

2. **Application shell and navigation**
   - `js/app.js` is the bootstrap layer that wires together authentication, routing, UI rendering, and feature modules.
   - `js/routing.js` controls in-app page/view switching without full page reloads, while `js/ui.js` handles the main dashboard and shared UI composition.

3. **Firebase as the primary backend boundary**
   - `js/firebase-config.js` supplies the Firebase project connection.
   - `js/db.js` is the main data-access layer for Firestore reads/writes, so most feature modules do not talk to Firebase directly.
   - The repo also includes `firestore.rules` and `firestore.indexes.json`, which are important because access control and query performance are part of the architecture, not just implementation detail.

4. **Identity, profile, and permissions**
   - `js/auth.js` manages sign-in, sign-up, logout, and password reset flows.
   - `js/profile.js` stores and updates user-specific academic metadata such as department, semester, and section.
   - `js/permission-manager.js` and related role logic split behavior for regular users, admins, CRs, and blocked users. This role boundary drives what data and actions are exposed in the UI.

5. **Core academic data model**
   - The central user-visible content comes from Firestore collections for tasks, events, and resource links.
   - The dashboard is personalized by the user profile: tasks are filtered by department/semester/section, while events can be department-scoped or global.
   - `resourceLinks` provides department-specific routine/calendar/faculty links, which are rendered as the main “resource cards” on the home screen.

6. **Calendar and task visualization**
   - `js/calendar-view.js` renders the monthly/weekly calendar interface and visualizes tasks on dates.
   - The calendar consumes the same task/event data used elsewhere, so it is a secondary view over the core Firestore content rather than a separate dataset.
   - Responsive behavior is important here; the README highlights a mobile monthly/weekly toggle, and the dedicated `css/calendar.css` plus `css/responsive.css` support that layout boundary.

7. **Activity tracking and timeline**
   - `js/activity-logger.js` records user actions such as logins or content changes.
   - `js/timeline-data.js` transforms logged activity into chart-ready data, and `js/timeline-ui.js` renders the heatmap/bar-chart style timeline.
   - `js/migrate-activity-logs.js` is a maintenance path for backfilling or restructuring existing activity records, so the timeline is a derived view over historical logs.

8. **Notifications and live updates**
   - `js/notification-manager.js`, `js/notification-content-formatter.js`, and `js/notifications-types.js` define how user-facing notifications are built and delivered.
   - `js/firestore-listener-manager.js` suggests a live-listener layer coordinating real-time Firestore updates that can trigger notifications or UI refreshes.
   - `js/offline-indicator.js` and `js/offline-manager.js` indicate that connectivity state is surfaced to the user and may affect how updates are queued or displayed.

9. **Notes and document attachment**
   - `js/notes.js` is a separate personal-content subsystem for markdown notes and file uploads.
   - The README notes external file-hosting support for uploads, so document storage is intentionally decoupled from Firestore and likely treated as links/attachments rather than binary blobs in the core database.
   - This is a user-owned workspace feature, distinct from shared academic tasks/events.

10. **Google Classroom integration**
   - `js/classroom.js` and `js/facultyClassroom.js` connect the app to Google Classroom data.
   - The README describes OAuth session persistence and a sync flow that brings classroom assignments/announcements into the unified task experience.
   - Architecturally, this is an external-source ingestion path: Classroom is read/synced into the app, then normalized into the same task-centric UI as native Firestore entries.

11. **Admin and privileged server-side operations**
   - `functions/index.js` is the Firebase Cloud Functions entry point, with admin helpers in `functions/admin/` such as `deleteUser.js` and `sendPasswordReset.js`.
   - These functions form the privileged boundary for operations that should not run purely in the browser, complementing Firestore security rules.
   - `js/admin-api.js` is the client-side companion for calling or coordinating those admin operations.

12. **PWA, caching, and offline support**
   - `sw.js`, `js/cache-manager.js`, `js/pwa-init.js`, `js/install-prompt.js`, `js/pwa-detector.js`, and `js/sw-update-manager.js` make the app installable and cache-aware.
   - `manifest.json` and the service worker define the app shell/offline behavior, so the architecture includes a browser cache layer in front of Firebase-backed content.

13. **Non-runtime documentation and verification**
   - `doc/` and `Archive/` contain extensive design notes, implementation plans, tests, and summaries. They are important for understanding feature history but are not part of the live runtime.
   - The archived tests show prior attention to calendar accessibility, navigation, and integration, which supports the idea that the calendar and task views are a major subsystem.

14. **Primary end-to-end data flow**
   - User opens the SPA → Firebase auth establishes identity → profile metadata is loaded → Firestore content is filtered by role and academic scope → dashboard/calendar/timeline/notifications render derived views.
   - External sources like Google Classroom and the notice backend feed into the same client, while Cloud Functions handle privileged operations and the service worker handles offline/cache behavior.

Main entry points: [`js/app.js`](https://github.com/b1tranger/b1t-sched/blob/main/js/app.js) (Bootstrap), [`js/ui.js`](https://github.com/b1tranger/b1t-sched/blob/main/js/ui.js) (Dashboard UI), [`js/db.js`](https://github.com/b1tranger/b1t-sched/blob/main/js/db.js) (Data layer), [`sw.js`](https://github.com/b1tranger/b1t-sched/blob/main/sw.js) (Service worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_client["Client SPA"]
  node_index_html["App shell<br/>entry html<br/>[index.html]"]
  node_app_js["Bootstrap<br/>spa entry<br/>[app.js]"]
  node_routing_js["Routing<br/>view router<br/>[routing.js]"]
  node_ui_js["Dashboard UI<br/>shell UI<br/>[ui.js]"]
  node_auth_js["Auth<br/>identity flows<br/>[auth.js]"]
  node_profile_js["Profile<br/>user metadata<br/>[profile.js]"]
  node_permission_js["Roles<br/>access control"]
  node_admin_api["Admin API<br/>client bridge<br/>[admin-api.js]"]
end

subgraph group_group_features["Feature Modules"]
  node_tasks_events["Tasks & events<br/>academic content<br/>[db.js]"]
  node_resource_links["Resource cards<br/>department links<br/>[db.js]"]
  node_calendar_js(("Calendar<br/>date view<br/>[calendar-view.js]"))
  node_timeline_data["Timeline data<br/>derived activity<br/>[timeline-data.js]"]
  node_timeline_ui["Timeline UI<br/>activity view<br/>[timeline-ui.js]"]
  node_activity_logger["Activity log<br/>event tracking<br/>[activity-logger.js]"]
  node_notes_js["Notes<br/>personal workspace<br/>[notes.js]"]
  node_classroom_js["Classroom sync<br/>external ingest<br/>[classroom.js]"]
  node_faculty_classroom["Faculty sync<br/>classroom integration"]
  node_notifications["Notifications<br/>delivery engine"]
  node_notif_formatter["Formatter<br/>message shaping"]
  node_notif_types["Notif types<br/>taxonomy"]
end

subgraph group_group_backend["Firebase Backend"]
  node_db_js[("Data layer<br/>firestore access<br/>[db.js]")]
  node_firebase_cfg["Firebase config<br/>project config<br/>[firebase-config.js]"]
  node_firestore_rules["Rules<br/>security policy<br/>[firestore.rules]"]
  node_firestore_indexes["Indexes"]
  node_functions_index["Cloud functions<br/>privileged backend<br/>[index.js]"]
  node_admin_funcs["Admin ops<br/>server helpers<br/>[deleteUser.js]"]
  node_listener_mgr["Firestore listeners<br/>realtime sync"]
end

subgraph group_group_delivery["PWA & Offline"]
  node_offline_manager["Offline manager<br/>connectivity state<br/>[offline-manager.js]"]
  node_offline_indicator["Offline indicator<br/>ui status"]
  node_cache_manager["Cache manager<br/>asset cache<br/>[cache-manager.js]"]
  node_pwa_init["PWA init<br/>installable app<br/>[pwa-init.js]"]
  node_install_prompt["Install prompt<br/>prompt UI<br/>[install-prompt.js]"]
  node_sw_update["SW updates<br/>update flow"]
  node_sw_js["Service worker<br/>offline runtime<br/>[sw.js]"]
end

node_index_html -->|"loads"| node_app_js
node_app_js -->|"initializes"| node_firebase_cfg
node_app_js -->|"auth flow"| node_auth_js
node_app_js -->|"navigation"| node_routing_js
node_app_js -->|"renders"| node_ui_js
node_ui_js -->|"role-aware UI"| node_permission_js
node_auth_js -->|"loads profile"| node_profile_js
node_profile_js -->|"scope"| node_permission_js
node_db_js -->|"serves"| node_tasks_events
node_db_js -->|"serves"| node_resource_links
node_ui_js -->|"shows"| node_tasks_events
node_ui_js -->|"shows"| node_resource_links
node_calendar_js -->|"consumes"| node_tasks_events
node_calendar_js -->|"embedded in"| node_ui_js
node_activity_logger -->|"feeds"| node_timeline_data
node_timeline_data -->|"renders"| node_timeline_ui
node_listener_mgr -->|"triggers"| node_notifications
node_notif_types -->|"classifies"| node_notif_formatter
node_notif_formatter -->|"builds"| node_notifications
node_classroom_js -->|"syncs into"| node_tasks_events
node_faculty_classroom -->|"specializes"| node_classroom_js
node_notes_js -->|"stores metadata"| node_db_js
node_admin_api -->|"calls"| node_functions_index
node_functions_index -->|"executes"| node_admin_funcs
node_firestore_rules -->|"protects"| node_db_js
node_firestore_indexes -->|"optimizes"| node_db_js
node_offline_manager -->|"updates"| node_offline_indicator
node_cache_manager -->|"coordinates"| node_sw_js
node_pwa_init -->|"registers"| node_sw_js
node_install_prompt -->|"supports"| node_pwa_init
node_sw_update -->|"updates"| node_sw_js
node_offline_manager -->|"adapts"| node_cache_manager

click node_index_html "https://github.com/b1tranger/b1t-sched/blob/main/index.html"
click node_app_js "https://github.com/b1tranger/b1t-sched/blob/main/js/app.js"
click node_routing_js "https://github.com/b1tranger/b1t-sched/blob/main/js/routing.js"
click node_ui_js "https://github.com/b1tranger/b1t-sched/blob/main/js/ui.js"
click node_auth_js "https://github.com/b1tranger/b1t-sched/blob/main/js/auth.js"
click node_profile_js "https://github.com/b1tranger/b1t-sched/blob/main/js/profile.js"
click node_permission_js "https://github.com/b1tranger/b1t-sched/blob/main/js/permission-manager.js"
click node_db_js "https://github.com/b1tranger/b1t-sched/blob/main/js/db.js"
click node_firebase_cfg "https://github.com/b1tranger/b1t-sched/blob/main/js/firebase-config.js"
click node_firestore_rules "https://github.com/b1tranger/b1t-sched/blob/main/firestore.rules"
click node_firestore_indexes "https://github.com/b1tranger/b1t-sched/blob/main/firestore.indexes.json"
click node_functions_index "https://github.com/b1tranger/b1t-sched/blob/main/functions/index.js"
click node_admin_funcs "https://github.com/b1tranger/b1t-sched/blob/main/functions/admin/deleteUser.js"
click node_admin_api "https://github.com/b1tranger/b1t-sched/blob/main/js/admin-api.js"
click node_tasks_events "https://github.com/b1tranger/b1t-sched/blob/main/js/db.js"
click node_resource_links "https://github.com/b1tranger/b1t-sched/blob/main/js/db.js"
click node_calendar_js "https://github.com/b1tranger/b1t-sched/blob/main/js/calendar-view.js"
click node_timeline_data "https://github.com/b1tranger/b1t-sched/blob/main/js/timeline-data.js"
click node_timeline_ui "https://github.com/b1tranger/b1t-sched/blob/main/js/timeline-ui.js"
click node_activity_logger "https://github.com/b1tranger/b1t-sched/blob/main/js/activity-logger.js"
click node_notes_js "https://github.com/b1tranger/b1t-sched/blob/main/js/notes.js"
click node_classroom_js "https://github.com/b1tranger/b1t-sched/blob/main/js/classroom.js"
click node_faculty_classroom "https://github.com/b1tranger/b1t-sched/blob/main/js/facultyClassroom.js"
click node_notifications "https://github.com/b1tranger/b1t-sched/blob/main/js/notification-manager.js"
click node_notif_formatter "https://github.com/b1tranger/b1t-sched/blob/main/js/notification-content-formatter.js"
click node_notif_types "https://github.com/b1tranger/b1t-sched/blob/main/js/notifications-types.js"
click node_listener_mgr "https://github.com/b1tranger/b1t-sched/blob/main/js/firestore-listener-manager.js"
click node_offline_manager "https://github.com/b1tranger/b1t-sched/blob/main/js/offline-manager.js"
click node_offline_indicator "https://github.com/b1tranger/b1t-sched/blob/main/js/offline-indicator.js"
click node_cache_manager "https://github.com/b1tranger/b1t-sched/blob/main/js/cache-manager.js"
click node_pwa_init "https://github.com/b1tranger/b1t-sched/blob/main/js/pwa-init.js"
click node_install_prompt "https://github.com/b1tranger/b1t-sched/blob/main/js/install-prompt.js"
click node_sw_update "https://github.com/b1tranger/b1t-sched/blob/main/js/sw-update-manager.js"
click node_sw_js "https://github.com/b1tranger/b1t-sched/blob/main/sw.js"

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_index_html,node_app_js,node_routing_js,node_ui_js,node_auth_js,node_profile_js,node_permission_js,node_admin_api toneBlue
class node_tasks_events,node_resource_links,node_calendar_js,node_timeline_data,node_timeline_ui,node_activity_logger,node_notes_js,node_classroom_js,node_faculty_classroom,node_notifications,node_notif_formatter,node_notif_types toneAmber
class node_db_js,node_firebase_cfg,node_firestore_rules,node_firestore_indexes,node_functions_index,node_admin_funcs,node_listener_mgr toneMint
class node_offline_manager,node_offline_indicator,node_cache_manager,node_pwa_init,node_install_prompt,node_sw_update,node_sw_js toneRose
```

## Components

### Client SPA

Browser runtime, shell, and feature modules

- [App shell](https://github.com/b1tranger/b1t-sched/blob/main/index.html): entry html · Top-level HTML entry point for the single-page application · `index.html`
- [Bootstrap](https://github.com/b1tranger/b1t-sched/blob/main/js/app.js): spa entry · Initial application wiring for auth, routing, and UI startup · `js/app.js`
- [Routing](https://github.com/b1tranger/b1t-sched/blob/main/js/routing.js): view router · In-app page and view switching without full reloads · `js/routing.js`
- [Dashboard UI](https://github.com/b1tranger/b1t-sched/blob/main/js/ui.js): shell UI · Shared UI composition and main dashboard rendering · `js/ui.js`
- [Auth](https://github.com/b1tranger/b1t-sched/blob/main/js/auth.js): identity flows · Sign-in, sign-up, logout, and password reset flows · `js/auth.js`
- [Profile](https://github.com/b1tranger/b1t-sched/blob/main/js/profile.js): user metadata · Stores academic profile fields such as department, semester, and section · `js/profile.js`
- [Roles](https://github.com/b1tranger/b1t-sched/blob/main/js/permission-manager.js): access control · Client-side role and permission logic for users, admins, CRs, and blocked users · `js/permission-manager.js`
- [Admin API](https://github.com/b1tranger/b1t-sched/blob/main/js/admin-api.js): client bridge · Client-side companion for calling privileged admin operations · `js/admin-api.js`

### Feature Modules

User-facing subsystems built on top of shared data and UI

- [Tasks & events](https://github.com/b1tranger/b1t-sched/blob/main/js/db.js): academic content · Core shared Firestore content that feeds the dashboard and calendar · `js/db.js`
- [Resource cards](https://github.com/b1tranger/b1t-sched/blob/main/js/db.js): department links · Department-specific routine, calendar, and faculty links on the home screen · `js/db.js`
- [Calendar](https://github.com/b1tranger/b1t-sched/blob/main/js/calendar-view.js): date view · Monthly and weekly task/event visualization · `js/calendar-view.js`
- [Timeline data](https://github.com/b1tranger/b1t-sched/blob/main/js/timeline-data.js): derived activity · Transforms activity logs into chart-ready timeline data · `js/timeline-data.js`
- [Timeline UI](https://github.com/b1tranger/b1t-sched/blob/main/js/timeline-ui.js): activity view · Renders the activity heatmap and bar-style timeline · `js/timeline-ui.js`
- [Activity log](https://github.com/b1tranger/b1t-sched/blob/main/js/activity-logger.js): event tracking · Records logins and content changes for later visualization · `js/activity-logger.js`
- [Notes](https://github.com/b1tranger/b1t-sched/blob/main/js/notes.js): personal workspace · Markdown notes and file attachment handling for user-owned content · `js/notes.js`
- [Classroom sync](https://github.com/b1tranger/b1t-sched/blob/main/js/classroom.js): external ingest · Google Classroom connection and sync into the task-centric app model · `js/classroom.js`
- [Faculty sync](https://github.com/b1tranger/b1t-sched/blob/main/js/facultyClassroom.js): classroom integration · Faculty-specific Classroom workflows and ingestion paths · `js/facultyClassroom.js`
- [Notifications](https://github.com/b1tranger/b1t-sched/blob/main/js/notification-manager.js): delivery engine · Builds and delivers user-facing notifications · `js/notification-manager.js`
- [Formatter](https://github.com/b1tranger/b1t-sched/blob/main/js/notification-content-formatter.js): message shaping · Formats notification payloads for display · `js/notification-content-formatter.js`
- [Notif types](https://github.com/b1tranger/b1t-sched/blob/main/js/notifications-types.js): taxonomy · Notification type definitions and categorization · `js/notifications-types.js`

### Firebase Backend

Firestore, security, and privileged server-side operations

- [Data layer](https://github.com/b1tranger/b1t-sched/blob/main/js/db.js): firestore access · Central Firestore reads and writes used by feature modules · `js/db.js`
- [Firebase config](https://github.com/b1tranger/b1t-sched/blob/main/js/firebase-config.js): project config · Firebase project connection settings used by the client · `js/firebase-config.js`
- [Rules](https://github.com/b1tranger/b1t-sched/blob/main/firestore.rules): security policy · Firestore access-control boundary · `firestore.rules`
- [Indexes](https://github.com/b1tranger/b1t-sched/blob/main/firestore.indexes.json): query indexes · Firestore query performance and compound index definitions · `firestore.indexes.json`
- [Cloud functions](https://github.com/b1tranger/b1t-sched/blob/main/functions/index.js): privileged backend · Firebase Cloud Functions entry point for server-side operations · `functions/index.js`
- [Admin ops](https://github.com/b1tranger/b1t-sched/blob/main/functions/admin/deleteUser.js): server helpers · Privileged operations such as user deletion and password reset · `functions/admin/deleteUser.js`
- [Firestore listeners](https://github.com/b1tranger/b1t-sched/blob/main/js/firestore-listener-manager.js): realtime sync · Coordinates live Firestore updates for refresh and notifications · `js/firestore-listener-manager.js`

### PWA & Offline

Caching, installability, and connectivity handling

- [Offline manager](https://github.com/b1tranger/b1t-sched/blob/main/js/offline-manager.js): connectivity state · Tracks connectivity and queues or adapts behavior when offline · `js/offline-manager.js`
- [Offline indicator](https://github.com/b1tranger/b1t-sched/blob/main/js/offline-indicator.js): ui status · Surfaces connectivity state to the user · `js/offline-indicator.js`
- [Cache manager](https://github.com/b1tranger/b1t-sched/blob/main/js/cache-manager.js): asset cache · Coordinates app-shell caching and local asset retention · `js/cache-manager.js`
- [PWA init](https://github.com/b1tranger/b1t-sched/blob/main/js/pwa-init.js): installable app · Initializes progressive-web-app behavior · `js/pwa-init.js`
- [Install prompt](https://github.com/b1tranger/b1t-sched/blob/main/js/install-prompt.js): prompt UI · Handles browser install prompt flows · `js/install-prompt.js`
- [SW updates](https://github.com/b1tranger/b1t-sched/blob/main/js/sw-update-manager.js): update flow · Manages service-worker update detection and refresh behavior · `js/sw-update-manager.js`
- [Service worker](https://github.com/b1tranger/b1t-sched/blob/main/sw.js): offline runtime · Caches and serves the app shell for offline use · `sw.js`

## Connections

- App shell → Bootstrap: loads · HTML bootstraps the SPA script
- Bootstrap → Firebase config: initializes · App connects to Firebase using shared config
- Bootstrap → Auth: auth flow · Bootstrap wires authentication
- Bootstrap → Routing: navigation · Bootstrap wires in-app routing
- Bootstrap → Dashboard UI: renders · Bootstrap mounts the shared UI shell
- Dashboard UI → Roles: role-aware UI · Dashboard adapts to user roles and blocked state
- Auth → Profile: loads profile · Authentication leads to loading academic metadata
- Profile → Roles: scope · Profile data informs role and access decisions
- Data layer → Tasks & events: serves · Firestore data layer feeds core academic content
- Data layer → Resource cards: serves · Data layer supplies department resource cards
- Dashboard UI → Tasks & events: shows · Dashboard renders the main content feed
- Dashboard UI → Resource cards: shows · Dashboard renders resource cards
- Calendar → Tasks & events: consumes · Calendar visualizes the same task/event dataset
- Calendar → Dashboard UI: embedded in · Calendar is one of the main views in the shell
- Activity log → Timeline data: feeds · Logs are transformed into chart-ready aggregates
- Timeline data → Timeline UI: renders · Derived activity data is displayed in the timeline view
- Firestore listeners → Notifications: triggers · Realtime updates can produce user notifications
- Notif types → Formatter: classifies · Notification types guide message formatting
- Formatter → Notifications: builds · Formatted content is handed to the delivery layer
- Classroom sync → Tasks & events: syncs into · Classroom assignments and announcements are normalized into tasks
- Faculty sync → Classroom sync: specializes · Faculty-specific Classroom behavior extends the core integration
- Notes → Data layer: stores metadata · Notes subsystem persists its user content through the data layer
- Admin API → Cloud functions: calls · Client-side admin bridge reaches privileged backend operations
- Cloud functions → Admin ops: executes · Cloud Functions expose admin helpers
- Rules → Data layer: protects · Security rules constrain data access from the client
- Indexes → Data layer: optimizes · Indexes support the query patterns used by the data layer
- Offline manager → Offline indicator: updates · Connectivity state is surfaced in the UI
- Cache manager → Service worker: coordinates · Caching logic works with the service worker
- PWA init → Service worker: registers · PWA startup registers the service worker
- Install prompt → PWA init: supports · Install prompt is part of the PWA startup flow
- SW updates → Service worker: updates · Update manager reacts to service-worker lifecycle changes
- Offline manager → Cache manager: adapts · Offline state influences caching and queued behavior