# comp47250-team-project/aegis architecture

> Architecture diagram of the GitHub repository comp47250-team-project/aegis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/comp47250-team-project/aegis
- Repository: https://github.com/comp47250-team-project/aegis

## Overview

AEGIS supports the full exam lifecycle: professors create and schedule quizzes, enroll students, and configure open-book resources; students take and submit exams while the browser sends answers separately from behavioral telemetry. Telemetry feeds live estimates and final integrity scoring, which professors review alongside timelines, grading, and exports. AI-assisted briefs, grading, and similarity checks are optional. The README documents several subsystem links not visible in sampled source; those are represented at the documented subsystem level, not as inferred internal call chains.

Main entry points: [`backend/app/main.py`](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/database.py`](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/database.py) (Application database), [`frontend/src/App.tsx`](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/App.tsx) (Role-based app), [`frontend/src/api/client.ts`](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Role-based app<br/>[App.tsx]"]
  node_examui["Exam interface<br/>[ExamShell.tsx]"]
  node_profui["Professor console"]
  node_studentui["Student dashboard"]
  node_telemetrysdk["Telemetry SDK<br/>[TelemetryClient.ts]"]
  node_apiclient["API client<br/>[client.ts]"]
end

subgraph group_exam["Exam workflow"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_quiz["Quiz authoring<br/>[quizzes.py]"]
  node_exammgmt["Exam management<br/>[exams.py]"]
  node_enrollment["Groups and enrollment<br/>[groups.py]"]
  node_resources["Open-book resources<br/>[resources.py]"]
  node_session["Session and results<br/>[sessions.py]"]
  node_exports["CSV export<br/>[export.py]"]
end

subgraph group_integrity["Integrity scoring"]
  node_telemetryapi["Telemetry ingestion<br/>[telemetry.py]"]
  node_messaging["Event dispatch<br/>[messaging.py]"]
  node_worker["Scoring worker<br/>[scorer_worker.py]"]
  node_scorer["Signal scoring<br/>[dispatch.py]"]
  node_live["Live monitoring<br/>[live_monitor.py]"]
end

subgraph group_services["Supporting services"]
  node_ai["AI features"]
  node_aiapi["AI endpoints<br/>[ai.py]"]
  node_db[("Application database<br/>[database.py]")]
  node_resourcefiles["Resource storage"]
end

node_student(("Student"))
node_professor(("Professor"))
node_admin(("Administrator"))
node_blob[("Azure Blob Storage")]
node_servicebus["Azure Service Bus"]
node_aihosts["AI model provider"]

node_student -->|"uses"| node_webapp
node_professor -->|"uses"| node_webapp
node_admin -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_examui
node_webapp -->|"routes to"| node_profui
node_webapp -->|"routes to"| node_studentui
node_examui -->|"requests exam"| node_apiclient
node_profui -->|"manages exams"| node_apiclient
node_studentui -->|"loads results"| node_apiclient
node_examui -->|"records signals"| node_telemetrysdk
node_telemetrysdk -->|"sends events"| node_apiclient
node_apiclient -->|"HTTP requests"| node_api
node_api -->|"registers router"| node_auth
node_api -->|"registers router"| node_quiz
node_api -->|"registers router"| node_exammgmt
node_api -->|"registers router"| node_enrollment
node_api -->|"registers router"| node_resources
node_api -->|"registers router"| node_session
node_api -->|"registers router"| node_exports
node_api -->|"registers router"| node_telemetryapi
node_api -->|"registers router"| node_aiapi
node_telemetryapi -->|"dispatches events"| node_messaging
node_messaging -.->|"queues events"| node_servicebus
node_worker -.->|"consumes events"| node_servicebus
node_worker -->|"triggers scoring"| node_scorer
node_telemetryapi -.->|"scores in process"| node_scorer
node_scorer -->|"reads and writes"| node_db
node_live -->|"reads session data"| node_db
node_resources -->|"stores and loads"| node_resourcefiles
node_resourcefiles -.->|"stores files"| node_blob
node_aiapi -->|"requests AI features"| node_ai
node_ai -.->|"calls provider"| node_aihosts
node_quiz -->|"persists content"| node_db
node_exammgmt -->|"persists exams"| node_db
node_session -->|"reads and writes"| node_db
node_enrollment -->|"persists groups"| node_db
node_exports -->|"reads results"| node_db

click node_webapp "https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/App.tsx"
click node_examui "https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/pages/ExamShell.tsx"
click node_profui "https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/pages/ProfessorConsole.tsx"
click node_studentui "https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/pages/StudentDashboard.tsx"
click node_telemetrysdk "https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/telemetry/TelemetryClient.ts"
click node_apiclient "https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/main.py"
click node_auth "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/auth.py"
click node_quiz "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/quizzes.py"
click node_exammgmt "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/exams.py"
click node_enrollment "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/groups.py"
click node_resources "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/resources.py"
click node_session "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/sessions.py"
click node_exports "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/export.py"
click node_telemetryapi "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/telemetry.py"
click node_messaging "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/messaging.py"
click node_worker "https://github.com/comp47250-team-project/aegis/blob/main/backend/workers/scorer_worker.py"
click node_scorer "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/scoring/dispatch.py"
click node_live "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/live_monitor.py"
click node_ai "https://github.com/comp47250-team-project/aegis/tree/main/backend/app/services/ai"
click node_aiapi "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/ai.py"
click node_db "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/database.py"
click node_resourcefiles "https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/resource_storage.py"

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_webapp,node_examui,node_profui,node_studentui,node_telemetrysdk,node_apiclient toneBlue
class node_api,node_auth,node_quiz,node_exammgmt,node_enrollment,node_resources,node_session,node_exports,node_blob toneAmber
class node_telemetryapi,node_messaging,node_worker,node_scorer,node_live toneMint
class node_ai,node_aiapi,node_db,node_resourcefiles toneRose
class node_student,node_professor,node_admin,node_servicebus,node_aihosts toneIndigo
```

## Components

### Web experience

- [Role-based app](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Exam interface](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/pages/ExamShell.tsx): `frontend/src/pages/ExamShell.tsx`
- [Professor console](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/pages/ProfessorConsole.tsx): `frontend/src/pages/ProfessorConsole.tsx`
- [Student dashboard](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/pages/StudentDashboard.tsx): `frontend/src/pages/StudentDashboard.tsx`
- [Telemetry SDK](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/telemetry/TelemetryClient.ts): `frontend/src/telemetry/TelemetryClient.ts`
- [API client](https://github.com/comp47250-team-project/aegis/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Exam workflow

- [FastAPI application](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Quiz authoring](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/quizzes.py): `backend/app/routers/quizzes.py`
- [Exam management](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/exams.py): `backend/app/routers/exams.py`
- [Groups and enrollment](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/groups.py): `backend/app/routers/groups.py`
- [Open-book resources](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/resources.py): `backend/app/routers/resources.py`
- [Session and results](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/sessions.py): `backend/app/routers/sessions.py`
- [CSV export](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/export.py): `backend/app/routers/export.py`

### Integrity scoring

- [Telemetry ingestion](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/telemetry.py): `backend/app/routers/telemetry.py`
- [Event dispatch](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/messaging.py): `backend/app/services/messaging.py`
- [Scoring worker](https://github.com/comp47250-team-project/aegis/blob/main/backend/workers/scorer_worker.py): `backend/workers/scorer_worker.py`
- [Signal scoring](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/scoring/dispatch.py): `backend/app/services/scoring/dispatch.py`
- [Live monitoring](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/live_monitor.py): `backend/app/services/live_monitor.py`

### Supporting services

- [AI features](https://github.com/comp47250-team-project/aegis/tree/main/backend/app/services/ai): `backend/app/services/ai`
- [AI endpoints](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/routers/ai.py): `backend/app/routers/ai.py`
- [Application database](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/database.py): `backend/app/database.py`
- [Resource storage](https://github.com/comp47250-team-project/aegis/blob/main/backend/app/services/resource_storage.py): `backend/app/services/resource_storage.py`

### Other components

- **Student**
- **Professor**
- **Administrator**
- **Azure Blob Storage**
- **Azure Service Bus**
- **AI model provider**

## Connections

- Student → Role-based app: uses
- Professor → Role-based app: uses
- Administrator → Role-based app: uses
- Role-based app → Exam interface: routes to
- Role-based app → Professor console: routes to
- Role-based app → Student dashboard: routes to
- Exam interface → API client: requests exam
- Professor console → API client: manages exams
- Student dashboard → API client: loads results
- Exam interface → Telemetry SDK: records signals
- Telemetry SDK → API client: sends events
- API client → FastAPI application: HTTP requests
- FastAPI application → Authentication: registers router
- FastAPI application → Quiz authoring: registers router
- FastAPI application → Exam management: registers router
- FastAPI application → Groups and enrollment: registers router
- FastAPI application → Open-book resources: registers router
- FastAPI application → Session and results: registers router
- FastAPI application → CSV export: registers router
- FastAPI application → Telemetry ingestion: registers router
- FastAPI application → AI endpoints: registers router
- Telemetry ingestion → Event dispatch: dispatches events
- Event dispatch → Azure Service Bus: queues events
- Scoring worker → Azure Service Bus: consumes events
- Scoring worker → Signal scoring: triggers scoring
- Telemetry ingestion → Signal scoring: scores in process
- Signal scoring → Application database: reads and writes
- Live monitoring → Application database: reads session data
- Open-book resources → Resource storage: stores and loads
- Resource storage → Azure Blob Storage: stores files
- AI endpoints → AI features: requests AI features
- AI features → AI model provider: calls provider
- Quiz authoring → Application database: persists content
- Exam management → Application database: persists exams
- Session and results → Application database: reads and writes
- Groups and enrollment → Application database: persists groups
- CSV export → Application database: reads results