# the-sukhsingh/campus-connect architecture

> Architecture diagram of the GitHub repository the-sukhsingh/campus-connect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-sukhsingh/campus-connect
- Repository: https://github.com/the-sukhsingh/campus-connect

## Overview

##### Project type and purpose
- Campus Connect is a full-stack, PWA (Progressive Web App) built on Next.js (React) that centralizes campus operations (attendance, library, room booking, events, announcements, notes).
- Frontend and backend live in the same Next.js codebase: pages & API routes.

##### File structure
- Top-level: config files (Next, ESLint, PostCSS), public assets (service workers, Firebase config), scripts.
- src/app: Next.js “app router” routes, sub-directories for API endpoints under src/app/api.
- src/components: reusable React UI components.
- src/config: client & admin Firebase config.
- src/context: React context for Auth, Notifications, Theme.
- src/lib: database connection (dbConnect.js).
- src/models: Mongoose schemas for core domain (User, College, Attendance, Book, etc.).
- src/services: business-logic layer abstracting API and DB operations.
- src/utils: helper functions (fetch wrapper, cache, offline sync, role protection).

##### Extract insights from README
- Tech stack: Next.js (SSR/SSG), MongoDB Atlas, Firebase Authentication & Cloud Messaging, Azure Blob Storage, Vercel hosting.
- Features: role-based access (Admin, HOD, Faculty, Student), real-time notifications, offline support via service workers and IndexedDB.
- External dependencies: Firebase Auth & FCM, Azure Storage, MongoDB.

##### Main components & their interactions
a. User Devices (Browsers/Mobile)
- Runs the Next.js PWA client.
- Interacts with the Next.js server (SSR pages & CSR hydration).
- Registers Service Worker for offline support & push notifications.
b. Next.js Server (Vercel Serverless)
- Serves SSR/SSG pages under src/app.
- Exposes API routes under src/app/api via serverless functions.
- Auth middleware (middleware.js) enforces role protection.
c. Business Logic Layer
- src/services: orchestrates data flow between API handlers and data sources.
d. Data Sources
- MongoDB Atlas (via Mongoose models in src/models + dbConnect).
- Azure Blob Storage for file uploads (notes, assignments) via azureStorageService.
- Firebase Admin SDK for server-side messaging and token management.
e. External Services
- Firebase Authentication (client & admin).
- Firebase Cloud Messaging for push.
- IndexedDB (via offlineSync, cacheUtils) for offline data persistence.

##### Architectural patterns & design principles
- Layered architecture: Presentation (React/Next.js pages & components) → API layer (Next.js routes) → Service layer → Persistence.
- Role-based access control enforced by Next.js middleware & withRoleProtection HOC.
- PWA patterns: Service Worker, manifest.json, offline cache strategy.
- Client-server separation: UI uses fetchWrapper to call API routes.
- Domain-driven modules: one service + model per domain (e.g., attendanceService + Attendance model).

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "UI Layer"
    direction TB
    pages["Next.js App Router (src/app)"]:::frontend
    auth["Auth Pages"]:::frontend
    dashboard["Dashboard Pages"]:::frontend
    offline["Offline Page"]:::frontend
    unauthorized["Unauthorized Page"]:::frontend
    components["React Components"]:::frontend
    layout["Global Layout & Styles"]:::frontend
  end

  subgraph "PWA"
    direction TB
    sw["Service Worker"]:::frontend
    manifest["manifest.json"]:::frontend
  end

  subgraph "API Layer"
    direction TB
    api["API Routes"]:::backend
    attendanceAPI["Attendance API"]:::backend
    libraryAPI["Library Book API"]:::backend
    roomAPI["Room Booking API"]:::backend
    notificationsAPI["Notifications API"]:::backend
    userAPI["User Management API"]:::backend
    middleware["Auth Middleware"]:::backend
  end

  subgraph "Service Layer"
    direction TB
    services["Services"]:::backend
    azureService["Azure Blob Storage Service"]:::backend
  end

  subgraph "Utilities"
    direction TB
    fetchWrapper["fetchWrapper"]:::backend
    offlineSync["offlineSync & cacheUtils"]:::frontend
    roleProtect["withRoleProtection"]:::frontend
  end

  subgraph "Data Layer"
    direction TB
    dbConnect["DB Connect Utility"]:::data
    models["Mongoose Models"]:::data
    indexedDB["IndexedDB"]:::data
  end

  subgraph "External Services"
    direction TB
    mongo["MongoDB Atlas"]:::external
    firebaseAuth["Firebase Auth"]:::external
    firebaseFCM["Firebase Cloud Messaging"]:::external
    azureStorage["Azure Blob Storage"]:::external
    vercel["Vercel Hosting"]:::external
  end

  pages -->|"SSR/CSR requests"| vercel
  pages -->|"REST calls"| api
  pages -->|"uses"| fetchWrapper
  pages -->|"protected by"| roleProtect
  api -->|"enforced by"| middleware
  api -->|"routes to"| attendanceAPI
  api -->|"routes to"| libraryAPI
  api -->|"routes to"| roomAPI
  api -->|"routes to"| notificationsAPI
  api -->|"routes to"| userAPI
  api -->|"calls"| services
  services -->|"connects via"| dbConnect
  dbConnect -->|"connects to"| mongo
  services -->|"uses models"| models
  services -->|"uploads to"| azureStorage
  services -->|"sends via"| firebaseFCM
  sw -->|"syncs"| offlineSync
  sw -->|"caches"| indexedDB
  offlineSync --> indexedDB

  click pages "https://github.com/the-sukhsingh/campus-connect/tree/master/src/app"
  click auth "https://github.com/the-sukhsingh/campus-connect/tree/master/src/app/auth"
  click dashboard "https://github.com/the-sukhsingh/campus-connect/tree/master/src/app/dashboard"
  click offline "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/offline/page.js"
  click unauthorized "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/unauthorized/page.js"
  click components "https://github.com/the-sukhsingh/campus-connect/tree/master/src/components"
  click layout "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/layout.js"
  click api "https://github.com/the-sukhsingh/campus-connect/tree/master/src/app/api"
  click attendanceAPI "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/api/attendance/route.js"
  click libraryAPI "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/api/library/books/route.js"
  click roomAPI "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/api/room-bookings/route.js"
  click notificationsAPI "https://github.com/the-sukhsingh/campus-connect/blob/master/src/app/api/notifications/subscription/route.js"
  click userAPI "https://github.com/the-sukhsingh/campus-connect/tree/master/src/app/api/user"
  click dbConnect "https://github.com/the-sukhsingh/campus-connect/blob/master/src/lib/dbConnect.js"
  click models "https://github.com/the-sukhsingh/campus-connect/tree/master/src/models"
  click services "https://github.com/the-sukhsingh/campus-connect/tree/master/src/services"
  click azureService "https://github.com/the-sukhsingh/campus-connect/blob/master/src/services/azureStorageService.js"
  click sw "https://github.com/the-sukhsingh/campus-connect/blob/master/public/service-worker.js"
  click fetchWrapper "https://github.com/the-sukhsingh/campus-connect/blob/master/src/utils/fetchWrapper.js"
  click offlineSync "https://github.com/the-sukhsingh/campus-connect/blob/master/src/utils/offlineSync.js"
  click roleProtect "https://github.com/the-sukhsingh/campus-connect/blob/master/src/utils/withRoleProtection.js"
  click middleware "https://github.com/the-sukhsingh/campus-connect/blob/master/middleware.js"

  classDef frontend fill:#D0E8FF,stroke:#0275d8,color:#0275d8
  classDef backend fill:#D6F5D6,stroke:#28a745,color:#155724
  classDef data fill:#FFE5B4,stroke:#fd7e14,color:#7a4100
  classDef external fill:#E2E3E5,stroke:#6c757d,color:#343a40
```
