# codemonk-io/campussync architecture

> Architecture diagram of the GitHub repository codemonk-io/campussync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/codemonk-io/campussync
- Repository: https://github.com/codemonk-io/campussync

## Overview

#### Purpose and entry points
This is a full-stack event-management application: users authenticate, create and browse events, register for them, comment, view personal dashboards, and optionally integrate calendars/reminders. The backend HTTP entry point is `backend/index.js`; the React/Vite client starts at `frontend/src/main.jsx` and composes application routing/UI in `frontend/src/App.jsx`.

#### Frontend application boundary
The browser client is a React single-page application with a centralized API layer and authentication context. `frontend/src/api.js` is the frontend/backend transport boundary; `frontend/src/context/AuthContext.jsx` owns client authentication state. Route protection is enforced in `frontend/src/components/layout/ProtectedRoute.jsx`, while key user workflows are implemented by pages such as `frontend/src/pages/EventsPage.jsx`, `frontend/src/pages/EventDetailPage.jsx`, and `frontend/src/pages/user/DashboardPage.jsx`.

#### Backend HTTP and request pipeline
The Node backend is organized as route → controller → service → model. Route modules expose domain endpoints, including `backend/routes/auth.js`, `backend/routes/events.js`, and `backend/routes/registrations.js`. Controllers adapt HTTP requests/responses and delegate business work, e.g. `backend/controllers/eventController.js`, `backend/controllers/calendarController.js`, and `backend/controllers/dashboardController.js`. Authentication and centralized error handling form cross-cutting request boundaries in `backend/middleware/auth.js` and `backend/middleware/errorHandler.js`.

#### Core event and participation domain
Events are the central aggregate, represented by `backend/models/Event.js` and managed through `backend/services/eventService.js`. Registration is a separate relationship/domain workflow, with `backend/models/Registration.js` and `backend/services/registrationService.js`; this separation supports event capacity/attendance logic independently of event authoring. Event discussion is similarly isolated through `backend/models/Comment.js` and `backend/services/commentService.js`.

#### Identity and authorization
Users are persisted in `backend/models/User.js`. Authentication behavior is concentrated in `backend/services/authService.js` and exposed through `backend/controllers/authController.js`; protected backend operations pass through `backend/middleware/auth.js`. The repository also includes Google auth configuration at `backend/config/googleAuth.js`, indicating an external identity-provider integration alongside the application’s own auth flow.

#### Calendar, notifications, and asynchronous work
Calendar integration is handled as an external-service boundary by `backend/services/googleCalendarService.js`, invoked through `backend/controllers/calendarController.js`. Email delivery is encapsulated in `backend/services/emailService.js`. Reminder processing is separated from request handling: `backend/cron/reminderCron.js` schedules work, while `backend/services/reminderService.js` determines and sends reminder actions. Time-offset parsing resides in `backend/utils/parseOffset.js`, supporting reminder scheduling inputs.

#### Dashboard and data composition
Dashboard data is assembled server-side rather than directly in the client from individual models, through `backend/services/dashboardService.js` and `backend/controllers/dashboardController.js`. The resulting user-facing view is rendered by `frontend/src/pages/user/DashboardPage.jsx`; organizer-specific presentation is represented by `frontend/src/components/events/OrganizerDashboardModal.jsx`. This creates a clear composition boundary for derived, multi-domain event and registration data.

Main entry points: [`backend/controllers/eventController.js`](https://github.com/codemonk-io/campussync/blob/main/backend/controllers/eventController.js) (HTTP controllers), [`backend/models/Event.js`](https://github.com/codemonk-io/campussync/blob/main/backend/models/Event.js) (Domain models), [`frontend/src/App.jsx`](https://github.com/codemonk-io/campussync/blob/main/frontend/src/App.jsx) (App routing), [`frontend/src/api.js`](https://github.com/codemonk-io/campussync/blob/main/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React client"]
  node_client_entry["Vite entry<br/>frontend entry<br/>[main.jsx]"]
  node_app["App routing<br/>React app<br/>[App.jsx]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.jsx]"]
  node_protected_route["Protected routes<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_event_pages["Event workflows<br/>React pages<br/>[EventsPage.jsx]"]
  node_dashboard_ui["User dashboard<br/>React page<br/>[DashboardPage.jsx]"]
  node_api["API client<br/>transport layer<br/>[api.js]"]
end

subgraph group_http["Backend HTTP"]
  node_server["HTTP entry<br/>Node server<br/>[index.js]"]
  node_routes["Domain routes<br/>Express routes<br/>[events.js]"]
  node_auth_middleware["Authentication<br/>middleware<br/>[auth.js]"]
  node_error_handler["Error handling<br/>middleware<br/>[errorHandler.js]"]
  node_controllers["HTTP controllers<br/>controller layer<br/>[eventController.js]"]
end

subgraph group_domain["Domain services"]
  node_auth_service["Authentication service<br/>[authService.js]"]
  node_event_service["Event service<br/>[eventService.js]"]
  node_registration_service["Registration service"]
  node_comment_service["Comment service<br/>[commentService.js]"]
  node_dashboard_service["Dashboard service<br/>composition service"]
  node_domain_models[("Domain models<br/>persistence models<br/>[Event.js]")]
end

subgraph group_async["Async &amp; integrations"]
  node_reminder_cron(("Reminder scheduler<br/>cron job<br/>[reminderCron.js]"))
  node_reminder_service["Reminder service<br/>[reminderService.js]"]
  node_email_service["Email delivery<br/>[emailService.js]"]
  node_calendar_service{{"Google Calendar<br/>external integration"}}
  node_google_identity{{"Google identity<br/>identity provider<br/>[googleAuth.js]"}}
end

node_client_entry -->|"mounts"| node_app
node_app -->|"uses"| node_auth_context
node_app -->|"guards routes with"| node_protected_route
node_app -->|"renders"| node_event_pages
node_app -->|"renders"| node_dashboard_ui
node_auth_context -->|"auth requests"| node_api
node_event_pages -->|"event requests"| node_api
node_dashboard_ui -->|"dashboard requests"| node_api
node_api -->|"HTTP"| node_server
node_server -->|"mounts"| node_routes
node_routes -->|"protected endpoints"| node_auth_middleware
node_auth_middleware -->|"authorizes"| node_controllers
node_routes -->|"dispatches"| node_controllers
node_server -.->|"errors"| node_error_handler
node_controllers -->|"auth"| node_auth_service
node_controllers -->|"events"| node_event_service
node_controllers -->|"registrations"| node_registration_service
node_controllers -->|"dashboard"| node_dashboard_service
node_controllers -->|"calendar actions"| node_calendar_service
node_auth_service -->|"users"| node_domain_models
node_auth_service -->|"external sign-in"| node_google_identity
node_event_service -->|"events"| node_domain_models
node_registration_service -->|"registrations"| node_domain_models
node_comment_service -->|"comments"| node_domain_models
node_dashboard_service -->|"composes from"| node_domain_models
node_reminder_cron -->|"triggers"| node_reminder_service
node_reminder_service -->|"reads event participation"| node_domain_models
node_reminder_service -->|"sends reminders"| node_email_service

click node_client_entry "https://github.com/codemonk-io/campussync/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/codemonk-io/campussync/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/codemonk-io/campussync/blob/main/frontend/src/context/AuthContext.jsx"
click node_protected_route "https://github.com/codemonk-io/campussync/blob/main/frontend/src/components/layout/ProtectedRoute.jsx"
click node_event_pages "https://github.com/codemonk-io/campussync/blob/main/frontend/src/pages/EventsPage.jsx"
click node_dashboard_ui "https://github.com/codemonk-io/campussync/blob/main/frontend/src/pages/user/DashboardPage.jsx"
click node_api "https://github.com/codemonk-io/campussync/blob/main/frontend/src/api.js"
click node_server "https://github.com/codemonk-io/campussync/blob/main/backend/index.js"
click node_routes "https://github.com/codemonk-io/campussync/blob/main/backend/routes/events.js"
click node_auth_middleware "https://github.com/codemonk-io/campussync/blob/main/backend/middleware/auth.js"
click node_error_handler "https://github.com/codemonk-io/campussync/blob/main/backend/middleware/errorHandler.js"
click node_controllers "https://github.com/codemonk-io/campussync/blob/main/backend/controllers/eventController.js"
click node_auth_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/authService.js"
click node_event_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/eventService.js"
click node_registration_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/registrationService.js"
click node_comment_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/commentService.js"
click node_dashboard_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/dashboardService.js"
click node_domain_models "https://github.com/codemonk-io/campussync/blob/main/backend/models/Event.js"
click node_reminder_cron "https://github.com/codemonk-io/campussync/blob/main/backend/cron/reminderCron.js"
click node_reminder_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/reminderService.js"
click node_email_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/emailService.js"
click node_calendar_service "https://github.com/codemonk-io/campussync/blob/main/backend/services/googleCalendarService.js"
click node_google_identity "https://github.com/codemonk-io/campussync/blob/main/backend/config/googleAuth.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_client_entry,node_app,node_auth_context,node_protected_route,node_event_pages,node_dashboard_ui,node_api toneBlue
class node_server,node_routes,node_auth_middleware,node_error_handler,node_controllers toneAmber
class node_auth_service,node_event_service,node_registration_service,node_comment_service,node_dashboard_service,node_domain_models toneMint
class node_reminder_cron,node_reminder_service,node_email_service,node_calendar_service,node_google_identity toneRose
```

## Components

### React client

- [Vite entry](https://github.com/codemonk-io/campussync/blob/main/frontend/src/main.jsx): frontend entry · `frontend/src/main.jsx`
- [App routing](https://github.com/codemonk-io/campussync/blob/main/frontend/src/App.jsx): React app · `frontend/src/App.jsx`
- [Auth state](https://github.com/codemonk-io/campussync/blob/main/frontend/src/context/AuthContext.jsx): React context · `frontend/src/context/AuthContext.jsx`
- [Protected routes](https://github.com/codemonk-io/campussync/blob/main/frontend/src/components/layout/ProtectedRoute.jsx): route guard · `frontend/src/components/layout/ProtectedRoute.jsx`
- [Event workflows](https://github.com/codemonk-io/campussync/blob/main/frontend/src/pages/EventsPage.jsx): React pages · Browse, create, and view event details. · `frontend/src/pages/EventsPage.jsx`
- [User dashboard](https://github.com/codemonk-io/campussync/blob/main/frontend/src/pages/user/DashboardPage.jsx): React page · `frontend/src/pages/user/DashboardPage.jsx`
- [API client](https://github.com/codemonk-io/campussync/blob/main/frontend/src/api.js): transport layer · `frontend/src/api.js`

### Backend HTTP

- [HTTP entry](https://github.com/codemonk-io/campussync/blob/main/backend/index.js): Node server · `backend/index.js`
- [Domain routes](https://github.com/codemonk-io/campussync/blob/main/backend/routes/events.js): Express routes · Auth, event, and registration endpoints. · `backend/routes/events.js`
- [Authentication](https://github.com/codemonk-io/campussync/blob/main/backend/middleware/auth.js): middleware · Protects backend operations. · `backend/middleware/auth.js`
- [Error handling](https://github.com/codemonk-io/campussync/blob/main/backend/middleware/errorHandler.js): middleware · `backend/middleware/errorHandler.js`
- [HTTP controllers](https://github.com/codemonk-io/campussync/blob/main/backend/controllers/eventController.js): controller layer · Adapts requests to service calls. · `backend/controllers/eventController.js`

### Domain services

- [Authentication service](https://github.com/codemonk-io/campussync/blob/main/backend/services/authService.js): service · `backend/services/authService.js`
- [Event service](https://github.com/codemonk-io/campussync/blob/main/backend/services/eventService.js): service · Owns event authoring and event logic. · `backend/services/eventService.js`
- [Registration service](https://github.com/codemonk-io/campussync/blob/main/backend/services/registrationService.js): service · Handles capacity and attendance workflows. · `backend/services/registrationService.js`
- [Comment service](https://github.com/codemonk-io/campussync/blob/main/backend/services/commentService.js): service · `backend/services/commentService.js`
- [Dashboard service](https://github.com/codemonk-io/campussync/blob/main/backend/services/dashboardService.js): composition service · Builds derived multi-domain dashboard data. · `backend/services/dashboardService.js`
- [Domain models](https://github.com/codemonk-io/campussync/blob/main/backend/models/Event.js): persistence models · User, Event, Registration, and Comment records. · `backend/models/Event.js`

### Async & integrations

- [Reminder scheduler](https://github.com/codemonk-io/campussync/blob/main/backend/cron/reminderCron.js): cron job · `backend/cron/reminderCron.js`
- [Reminder service](https://github.com/codemonk-io/campussync/blob/main/backend/services/reminderService.js): service · Determines and sends reminder actions. · `backend/services/reminderService.js`
- [Email delivery](https://github.com/codemonk-io/campussync/blob/main/backend/services/emailService.js): service · `backend/services/emailService.js`
- [Google Calendar](https://github.com/codemonk-io/campussync/blob/main/backend/services/googleCalendarService.js): external integration · `backend/services/googleCalendarService.js`
- [Google identity](https://github.com/codemonk-io/campussync/blob/main/backend/config/googleAuth.js): identity provider · `backend/config/googleAuth.js`

## Connections

- Vite entry → App routing: mounts
- App routing → Auth state: uses
- App routing → Protected routes: guards routes with
- App routing → Event workflows: renders
- App routing → User dashboard: renders
- Auth state → API client: auth requests
- Event workflows → API client: event requests
- User dashboard → API client: dashboard requests
- API client → HTTP entry: HTTP
- HTTP entry → Domain routes: mounts
- Domain routes → Authentication: protected endpoints
- Authentication → HTTP controllers: authorizes
- Domain routes → HTTP controllers: dispatches
- HTTP entry → Error handling: errors
- HTTP controllers → Authentication service: auth
- HTTP controllers → Event service: events
- HTTP controllers → Registration service: registrations
- HTTP controllers → Dashboard service: dashboard
- HTTP controllers → Google Calendar: calendar actions
- Authentication service → Domain models: users
- Authentication service → Google identity: external sign-in
- Event service → Domain models: events
- Registration service → Domain models: registrations
- Comment service → Domain models: comments
- Dashboard service → Domain models: composes from
- Reminder scheduler → Reminder service: triggers
- Reminder service → Domain models: reads event participation
- Reminder service → Email delivery: sends reminders