# rissingh23/calendub-web architecture

> Architecture diagram of the GitHub repository rissingh23/calendub-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rissingh23/calendub-web
- Repository: https://github.com/rissingh23/calendub-web

## Overview

##### Project Type & Purpose
- CalenDUB is a full-stack, single-page web application (React + Tailwind CSS) backed by a Node.js/Express API and MongoDB.
- Purpose: aggregate and display University of Washington RSO events, enable RSVPs, reminders, and RSO-specific filtering.

##### File Structure
Top-level directories:
- client/ → React/Vite front-end
- server/ → Node.js/Express back-end
Supporting files:
- render.yaml → deployment config
- README.md → high-level overview
Key subdirectories:
- client/src/components & client/src/routes → UI components & pages
- client/src/context/AuthContext.tsx → React Context for authentication state
- client/src/utils/*.ts → client-side services (API wrappers, AI recommendations, email utils)
- server/models/ → Mongoose schemas (User, Event, Organizer, PersonalEvent)
- server/routes/ → Express routers (userRoutes, eventRoutes, organizerRoutes)
- server/middleware/auth.js & firebase/verifyToken.js → JWT & Firebase token validation
- server/config/database.js → MongoDB connection
- server/utils/emailUtils.js → outgoing email logic
- server/seed-data/ → DB seeding scripts

##### Extract Architectural Insights from README
- Frontend: React + Tailwind CSS; served on localhost:3000 via Vite
- Backend: Node.js, Express, JWT & Firebase Auth, MongoDB
- Features: directory search, RSVP/reminders, RSO filters, notifications

##### Main System Components
a. Frontend Client (Browser)
– React SPA (Pages + Reusable Components)
– AuthContext (manages JWT/Firebase ID tokens)
– API service layer (client/src/utils/api.ts using axios or fetch)
b. Backend API Server
– Express application (server/index.js & app.js)
– Routing layer (server/routes/*)
– Middleware for auth (JWT + Firebase verify)
– Controllers/business logic (in route handlers)
– Data access via Mongoose models (server/models/*.js)
c. Database
– MongoDB cluster (connected via server/config/database.js)
d. External Services
– Firebase Authentication (client for sign-in, server verifyToken, firebase-admin)
– Email service (SMTP or SendGrid via server/utils/emailUtils.js)
e. File Storage
– Local uploads folder (server/uploads/organizers)

##### Component Interactions & Data Flow
1. User interacts with React UI → triggers page/component events
2. Auth flow: GoogleLoginButton → Firebase Auth SDK → receives ID token → stored in AuthContext
3. Protected API calls: AuthContext attaches JWT/Firebase token to HTTP headers → sent to Express server
4. Express middleware verifies token (JWT or firebase-admin.verify) → passes request to router
5. Router handlers call Mongoose models → read/write MongoDB
6. If needed, server/utils/emailUtils sends email reminders/RSVP confirmations
7. Server responds → frontend updates UI state
8. Optional: client utils (aiRecommendations) may call third-party AI APIs

##### Architectural Patterns & Principles
– Layered architecture: Presentation (UI) → API layer → Business logic → Data access → Database
– MVC-style on server: Routes (Controllers) + Models (Mongoose)
– Separation of concerns: React components vs. service utils vs. context vs. styling
– Token-based authentication: JWT + Firebase custom claims
– Progressive enhancement: seed-data for local development, file-based uploads

[ ] Frontend (React SPA)
– UI Components & Pages
– AuthContext / Token store
– API Client Layer
[ ] Backend (Express API)
– Auth & Verification Middleware
– Route Handlers (user, event, organizer)
– Business Logic / Controllers
– Mongoose Models
– Configuration (DB connection)
[ ] MongoDB (Database)
[ ] Firebase Auth (External Auth Service)
[ ] Email Service (External Notification)
[ ] File Storage (uploads directory)
[ ] Deployment Platform (Render or other)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        direction TB
        MainTSX["main.tsx"]:::frontend
        AppTSX["App.tsx"]:::frontend
        Components["UI Components"]:::frontend
        Routes["Pages/Routes"]:::frontend
        AuthContext["AuthContext"]:::frontend
        APIClient["API Client"]:::frontend
        FirebaseSDK["Firebase Auth SDK"]:::frontend
        AIRec["AI Recommendations Utility"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Express API)"
        direction TB
        ExpressIndex["Express Entry (index.js)"]:::backend
        ExpressApp["App Setup (app.js)"]:::backend
        AuthMw["Authentication Middleware"]:::backend
        VerifyToken["Firebase Token Verification"]:::backend
        UserRoutes["User Routes"]:::backend
        EventRoutes["Event Routes"]:::backend
        OrganizerRoutes["Organizer Routes"]:::backend
        UserModel["User Model"]:::backend
        EventModel["Event Model"]:::backend
        OrganizerModel["Organizer Model"]:::backend
        PersonalEventModel["PersonalEvent Model"]:::backend
        DBConfig["Database Configuration"]:::backend
        EmailUtil["Email Service Utility"]:::backend
        FileStorage["File Storage (uploads)"]:::backend
        SeedData["Seed Data Scripts"]:::backend
        FirebaseAdmin["Firebase Admin SDK"]:::backend
    end

    %% Database
    DB["MongoDB"]:::database

    %% External Services
    ExternalFirebase["Firebase Auth Service"]:::external
    ExternalEmail["Email Service"]:::external

    %% Deployment
    Deployment["Deployment Config (render.yaml)"]:::deployment

    %% Frontend Flows
    MainTSX -->|imports| AppTSX
    AppTSX -->|renders| Components
    AppTSX -->|navigates| Routes
    Routes -->|uses| AuthContext
    AuthContext -->|provides token| APIClient
    APIClient -->|"HTTP/JSON + JWT"| ExpressIndex
    APIClient -->|optional calls| AIRec
    AuthContext -->|initial login| FirebaseSDK
    FirebaseSDK -->|OAuth| ExternalFirebase

    %% Backend Flows
    ExpressIndex -->|initialize| ExpressApp
    ExpressApp -->|use| AuthMw
    ExpressApp -->|use| VerifyToken
    ExpressApp -->|mount| UserRoutes
    ExpressApp -->|mount| EventRoutes
    ExpressApp -->|mount| OrganizerRoutes
    UserRoutes -->|CRUD| UserModel
    EventRoutes -->|CRUD| EventModel
    OrganizerRoutes -->|CRUD| OrganizerModel
    OrganizerRoutes -->|CRUD| PersonalEventModel
    UserModel -->|connect| DB
    EventModel -->|connect| DB
    OrganizerModel -->|connect| DB
    PersonalEventModel -->|connect| DB
    DBConfig -->|connect| DB
    AuthMw -->|verify| JWT
    VerifyToken -->|verify ID token| FirebaseAdmin
    ExpressApp -->|send emails| EmailUtil
    EmailUtil -->|SMTP/API| ExternalEmail
    ExpressApp -->|serve files| FileStorage
    SeedData -->|populate| DB

    %% Deployment Flows
    Deployment -->|deploys| ExpressIndex
    Deployment -->|deploys| MainTSX

    %% Click Events
    click MainTSX "https://github.com/rissingh23/calendub-web/blob/main/client/src/main.tsx"
    click AppTSX "https://github.com/rissingh23/calendub-web/blob/main/client/src/App.tsx"
    click Components "https://github.com/rissingh23/calendub-web/tree/main/client/src/components"
    click Routes "https://github.com/rissingh23/calendub-web/tree/main/client/src/routes"
    click AuthContext "https://github.com/rissingh23/calendub-web/blob/main/client/src/context/AuthContext.tsx"
    click APIClient "https://github.com/rissingh23/calendub-web/blob/main/client/src/utils/api.ts"
    click FirebaseSDK "https://github.com/rissingh23/calendub-web/blob/main/client/src/firebase/firebase.ts"
    click AIRec "https://github.com/rissingh23/calendub-web/blob/main/client/src/utils/aiRecommendations.ts"
    click ExpressIndex "https://github.com/rissingh23/calendub-web/blob/main/server/index.js"
    click ExpressApp "https://github.com/rissingh23/calendub-web/blob/main/server/app.js"
    click AuthMw "https://github.com/rissingh23/calendub-web/blob/main/server/middleware/auth.js"
    click VerifyToken "https://github.com/rissingh23/calendub-web/blob/main/server/firebase/verifyToken.js"
    click UserRoutes "https://github.com/rissingh23/calendub-web/blob/main/server/routes/userRoutes.js"
    click EventRoutes "https://github.com/rissingh23/calendub-web/blob/main/server/routes/eventRoutes.js"
    click OrganizerRoutes "https://github.com/rissingh23/calendub-web/blob/main/server/routes/organizerRoutes.js"
    click UserModel "https://github.com/rissingh23/calendub-web/blob/main/server/models/User.js"
    click EventModel "https://github.com/rissingh23/calendub-web/blob/main/server/models/Event.js"
    click OrganizerModel "https://github.com/rissingh23/calendub-web/blob/main/server/models/Organizer.js"
    click PersonalEventModel "https://github.com/rissingh23/calendub-web/blob/main/server/models/PersonalEvent.js"
    click DBConfig "https://github.com/rissingh23/calendub-web/blob/main/server/config/database.js"
    click EmailUtil "https://github.com/rissingh23/calendub-web/blob/main/server/utils/emailUtils.js"
    click FileStorage "https://github.com/rissingh23/calendub-web/tree/main/server/uploads/organizers"
    click SeedData "https://github.com/rissingh23/calendub-web/blob/main/server/seed-data/seed-events.js"
    click FirebaseAdmin "https://github.com/rissingh23/calendub-web/blob/main/server/firebase/firebase-admin.js"
    click Deployment "https://github.com/rissingh23/calendub-web/blob/main/render.yaml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef database fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef deployment fill:#F5DEB3,stroke:#333,stroke-width:1px
```
