# beacon-campus/beacon architecture

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

- Interactive diagram: https://gitdiagram.com/beacon-campus/beacon
- Repository: https://github.com/beacon-campus/beacon

## Overview

Beacon is a role-based campus collaboration platform for students, teachers, and administrators. Users sign in and complete onboarding, then enter role-specific home or community experiences to communicate, manage coursework, and access campus services; teachers publish and assess assignments, while admins manage users, classrooms, announcements, and operations. The React client calls an Express API, with MongoDB-backed domain data and Firebase identity. Chat and notifications also use Socket.IO, while uploads and AI assistance rely on external services. The graph follows README-described capabilities; unsampled module internals are represented by their existing directories.

Main entry points: [`server/controllers`](https://github.com/beacon-campus/beacon/tree/main/server/controllers) (Domain controllers), [`client/src/App.jsx`](https://github.com/beacon-campus/beacon/blob/main/client/src/App.jsx) (Role routing), [`server/models`](https://github.com/beacon-campus/beacon/tree/main/server/models) (MongoDB domain data), [`client/src/context/AuthContext.jsx`](https://github.com/beacon-campus/beacon/blob/main/client/src/context/AuthContext.jsx) (Sign-in onboarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Role routing<br/>[App.jsx]"]
  node_identity_ui["Sign-in onboarding<br/>[AuthContext.jsx]"]
  node_home_data["Home data"]
  node_api_client["API client<br/>[apiClient.js]"]
  node_admin_ui["Admin operations<br/>[AdminLayout.jsx]"]
  node_socket_ui["Realtime client<br/>[SocketManager.jsx]"]
end

subgraph group_learning["Learning collaboration"]
  node_chat_ui["Chat experience"]
  node_community_ui["Classroom community"]
  node_assignment_ui["Assignments quizzes"]
  node_personal_tools["Notes tasks sketch"]
  node_study_bot_ui["Study assistant"]
end

subgraph group_server["API and domain"]
  node_api["HTTP API<br/>[index.js]"]
  node_auth_middleware["Token verification<br/>[auth.js]"]
  node_domain_api["Domain controllers"]
  node_chat_service["Chat service<br/>[chat.service.js]"]
  node_assignment_service["Assignment workflows"]
  node_realtime["Socket service<br/>[socket.service.js]"]
  node_admin_metrics["Admin metrics logs<br/>[metrics.service.js]"]
end

subgraph group_data["Persistence and identity"]
  node_mongo[("MongoDB domain data")]
end

subgraph group_integrations["External services"]
  node_firebase[("Firebase identity")]
  node_cloudinary["Cloudinary uploads"]
  node_gemini["Gemini AI"]
  node_socket_io["Socket.IO transport"]
end

node_people(("Campus users"))

node_people -->|"sign in"| node_identity_ui
node_identity_ui -->|"authenticates with"| node_firebase
node_identity_ui -->|"loads profile through"| node_api_client
node_people -->|"uses"| node_app
node_app -.->|"routes to"| node_chat_ui
node_app -->|"routes to"| node_community_ui
node_app -->|"routes to"| node_assignment_ui
node_people -->|"views home data"| node_home_data
node_home_data -->|"fetches through"| node_api_client
node_people -->|"manages"| node_personal_tools
node_people -->|"asks questions"| node_study_bot_ui
node_people -->|"administers platform"| node_admin_ui
node_api_client -->|"sends API requests"| node_api
node_api -->|"verifies protected requests"| node_auth_middleware
node_api -->|"dispatches routes"| node_domain_api
node_domain_api -->|"delegates chat"| node_chat_service
node_domain_api -->|"delegates assignments"| node_assignment_service
node_chat_service -->|"reads and writes"| node_mongo
node_assignment_service -->|"stores coursework"| node_mongo
node_domain_api -.->|"accesses domain records"| node_mongo
node_domain_api -.->|"stores uploaded files"| node_cloudinary
node_domain_api -.->|"requests AI responses"| node_gemini
node_socket_ui -->|"exchanges events"| node_socket_io
node_realtime -->|"dispatches live events"| node_socket_io
node_socket_ui -.->|"receives updates from"| node_realtime
node_admin_ui -.->|"views operational metrics"| node_admin_metrics
node_admin_metrics -->|"samples domain counts"| node_mongo

click node_app "https://github.com/beacon-campus/beacon/blob/main/client/src/App.jsx"
click node_identity_ui "https://github.com/beacon-campus/beacon/blob/main/client/src/context/AuthContext.jsx"
click node_home_data "https://github.com/beacon-campus/beacon/blob/main/client/src/context/HomeDataContext.jsx"
click node_api_client "https://github.com/beacon-campus/beacon/blob/main/client/src/services/apiClient.js"
click node_chat_ui "https://github.com/beacon-campus/beacon/tree/main/client/src/components/chat_comps"
click node_community_ui "https://github.com/beacon-campus/beacon/tree/main/client/src/components/community_comps"
click node_assignment_ui "https://github.com/beacon-campus/beacon/blob/main/client/src/pages/teacher/teacher_community/TeacherPublishAssigment.jsx"
click node_personal_tools "https://github.com/beacon-campus/beacon/tree/main/client/src/pages/student/student_home"
click node_study_bot_ui "https://github.com/beacon-campus/beacon/blob/main/client/src/pages/student/student_home/StudentStudyBot.jsx"
click node_admin_ui "https://github.com/beacon-campus/beacon/blob/main/client/src/layouts/adminlayout/AdminLayout.jsx"
click node_socket_ui "https://github.com/beacon-campus/beacon/blob/main/client/src/components/SocketManager.jsx"
click node_api "https://github.com/beacon-campus/beacon/blob/main/server/index.js"
click node_auth_middleware "https://github.com/beacon-campus/beacon/blob/main/server/middleware/auth.js"
click node_domain_api "https://github.com/beacon-campus/beacon/tree/main/server/controllers"
click node_chat_service "https://github.com/beacon-campus/beacon/blob/main/server/services/chat.service.js"
click node_assignment_service "https://github.com/beacon-campus/beacon/blob/main/server/services/assignment.service.js"
click node_realtime "https://github.com/beacon-campus/beacon/blob/main/server/services/socket.service.js"
click node_admin_metrics "https://github.com/beacon-campus/beacon/blob/main/server/services/metrics.service.js"
click node_mongo "https://github.com/beacon-campus/beacon/tree/main/server/models"

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_app,node_identity_ui,node_home_data,node_api_client,node_admin_ui,node_socket_ui,node_people toneBlue
class node_chat_ui,node_community_ui,node_assignment_ui,node_personal_tools,node_study_bot_ui toneAmber
class node_api,node_auth_middleware,node_domain_api,node_chat_service,node_assignment_service,node_realtime,node_admin_metrics toneMint
class node_mongo toneRose
class node_firebase,node_cloudinary,node_gemini,node_socket_io toneIndigo
```

## Components

### Client experience

- [Role routing](https://github.com/beacon-campus/beacon/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Sign-in onboarding](https://github.com/beacon-campus/beacon/blob/main/client/src/context/AuthContext.jsx): `client/src/context/AuthContext.jsx`
- [Home data](https://github.com/beacon-campus/beacon/blob/main/client/src/context/HomeDataContext.jsx): `client/src/context/HomeDataContext.jsx`
- [API client](https://github.com/beacon-campus/beacon/blob/main/client/src/services/apiClient.js): `client/src/services/apiClient.js`
- [Admin operations](https://github.com/beacon-campus/beacon/blob/main/client/src/layouts/adminlayout/AdminLayout.jsx): `client/src/layouts/adminlayout/AdminLayout.jsx`
- [Realtime client](https://github.com/beacon-campus/beacon/blob/main/client/src/components/SocketManager.jsx): `client/src/components/SocketManager.jsx`

### Learning collaboration

- [Chat experience](https://github.com/beacon-campus/beacon/tree/main/client/src/components/chat_comps): `client/src/components/chat_comps`
- [Classroom community](https://github.com/beacon-campus/beacon/tree/main/client/src/components/community_comps): `client/src/components/community_comps`
- [Assignments quizzes](https://github.com/beacon-campus/beacon/blob/main/client/src/pages/teacher/teacher_community/TeacherPublishAssigment.jsx): `client/src/pages/teacher/teacher_community/TeacherPublishAssigment.jsx`
- [Notes tasks sketch](https://github.com/beacon-campus/beacon/tree/main/client/src/pages/student/student_home): `client/src/pages/student/student_home`
- [Study assistant](https://github.com/beacon-campus/beacon/blob/main/client/src/pages/student/student_home/StudentStudyBot.jsx): `client/src/pages/student/student_home/StudentStudyBot.jsx`

### API and domain

- [HTTP API](https://github.com/beacon-campus/beacon/blob/main/server/index.js): `server/index.js`
- [Token verification](https://github.com/beacon-campus/beacon/blob/main/server/middleware/auth.js): `server/middleware/auth.js`
- [Domain controllers](https://github.com/beacon-campus/beacon/tree/main/server/controllers): `server/controllers`
- [Chat service](https://github.com/beacon-campus/beacon/blob/main/server/services/chat.service.js): `server/services/chat.service.js`
- [Assignment workflows](https://github.com/beacon-campus/beacon/blob/main/server/services/assignment.service.js): `server/services/assignment.service.js`
- [Socket service](https://github.com/beacon-campus/beacon/blob/main/server/services/socket.service.js): `server/services/socket.service.js`
- [Admin metrics logs](https://github.com/beacon-campus/beacon/blob/main/server/services/metrics.service.js): `server/services/metrics.service.js`

### Persistence and identity

- [MongoDB domain data](https://github.com/beacon-campus/beacon/tree/main/server/models): `server/models`

### External services

- **Firebase identity**
- **Cloudinary uploads**
- **Gemini AI**
- **Socket.IO transport**

### Other components

- **Campus users**

## Connections

- Campus users → Sign-in onboarding: sign in
- Sign-in onboarding → Firebase identity: authenticates with
- Sign-in onboarding → API client: loads profile through (evidence: `client/src/context/AuthContext.jsx`)
- Campus users → Role routing: uses (evidence: `client/src/App.jsx`)
- Role routing → Chat experience: routes to
- Role routing → Classroom community: routes to (evidence: `client/src/App.jsx`)
- Role routing → Assignments quizzes: routes to (evidence: `client/src/App.jsx`)
- Campus users → Home data: views home data
- Home data → API client: fetches through (evidence: `client/src/context/HomeDataContext.jsx`)
- Campus users → Notes tasks sketch: manages
- Campus users → Study assistant: asks questions
- Campus users → Admin operations: administers platform
- API client → HTTP API: sends API requests
- HTTP API → Token verification: verifies protected requests (evidence: `server/middleware/auth.js`)
- HTTP API → Domain controllers: dispatches routes (evidence: `server/index.js`)
- Domain controllers → Chat service: delegates chat (evidence: `server/controllers/chat.controller.js`)
- Domain controllers → Assignment workflows: delegates assignments (evidence: `server/controllers/assignment.controller.js`)
- Chat service → MongoDB domain data: reads and writes (evidence: `server/services/chat.service.js`)
- Assignment workflows → MongoDB domain data: stores coursework (evidence: `server/controllers/assignment.controller.js`)
- Domain controllers → MongoDB domain data: accesses domain records (evidence: `server/controllers/assignment.controller.js`)
- Domain controllers → Cloudinary uploads: stores uploaded files
- Domain controllers → Gemini AI: requests AI responses
- Realtime client → Socket.IO transport: exchanges events (evidence: `client/src/components/SocketManager.jsx`)
- Socket service → Socket.IO transport: dispatches live events
- Realtime client → Socket service: receives updates from
- Admin operations → Admin metrics logs: views operational metrics
- Admin metrics logs → MongoDB domain data: samples domain counts (evidence: `server/services/metrics.service.js`)
