b1tranger/b1t-sched

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.