# cegit27/moodle-proctor architecture

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

- Interactive diagram: https://gitdiagram.com/cegit27/moodle-proctor
- Repository: https://github.com/cegit27/moodle-proctor

## Overview

##### What this project is (type + purpose)
From the repo root and the file tree, this looks like a **frontend-only (in this repo) Next.js application** for an **AI-powered online proctoring system integrated with Moodle**.

Key signals:
- `frontend/next.config.ts`, `frontend/app/...`, `page.tsx`, `layout.tsx` → **Next.js (App Router)** web UI.
- `frontend/src/services/api.ts` → an **HTTP API client** to talk to a backend (not present in this repo).
- `frontend/src/services/socket.ts` + `frontend/src/hooks/useSocket.ts` → a **WebSocket/Socket-based realtime channel** (typical for proctoring: live status, events, video session signaling, alerts).
- UI composition in `src/components/*` and feature routes in `app/dashboard`, `app/exams`, `app/login`.

##### Top-level
- `README.md` → minimal, but clearly “Moodle Proctoring” domain.
- `frontend/` → the deployable web app.

##### Next.js “feature slices” (routes)
- `frontend/app/login/page.tsx` → Login flow
- `frontend/app/dashboard/page.tsx` → Proctor dashboard / overview
- `frontend/app/exams/page.tsx` → Exams list / exam sessions

Also:
- `frontend/app/layout.tsx` → root layout (global nav, providers, theming)
- `frontend/app/globals.css` → styling baseline

##### Reusable UI building blocks
- `src/components/Navbar.tsx`
- `src/components/AlertPanel.tsx` (proctoring alerts are core)
- `src/components/StudentCard.tsx` (candidate status card)
- `src/components/VideoGrid.tsx` (live candidate streams / thumbnails)

##### Integration points (critical
These become **connectors to external containers**:
- `src/services/api.ts` → “Proctoring Backend REST API”
- `src/services/socket.ts` → “Realtime Server (WebSocket/Socket.IO)”
- `src/hooks/useSocket.ts` → the client-side wiring to realtime
- `src/utils/constants.ts` → environment/config values (API base URL, socket URL)
- `src/types/student.ts` → data contracts (student/candidate model)

##### Authentication
- User logs in via `LoginPage`
- Frontend calls Backend Auth endpoint (or Moodle SSO/LTI redirect)

##### Exam monitoring
- `ExamsPage` loads exam list via `api.ts`
- Selecting an exam loads roster/candidates
- `DashboardPage` subscribes to live events via `useSocket`

##### Realtime proctoring events
- Candidate events (face not detected, tab switch, multiple people) flow:
AI Engine → Backend → Realtime Server → Frontend `socket.ts` → UI (`AlertPanel`, `StudentCard` badges)

##### Video / media
- `VideoGrid` strongly suggests live video tiles.
- If the transport isn’t in repo (no WebRTC code visible), represent it as:
- “Video stream source (WebRTC/RTSP/3rd-party)” external to frontend
- UI receives stream URLs/tokens from backend, then renders streams

##### Diagramming conventions to use (clarity + detail)
Use these elements consistently:

- **Clear labels**:
- “Next.js Frontend (App Router)”
- “API Client (src/services/api.ts)”
- “Socket Client (src/services/socket.ts)”
- “Socket Hook (src/hooks/useSocket.ts)”
- “Moodle LMS (External)”
- “Proctoring Backend (External)”
- “Realtime Server (External)”

- `HTTPS/JSON: exam roster`
- `WSS: candidateStatusChanged event`
- `HTTPS: auth/SSO`

- Blue: UI/pages/components
- Purple: frontend integration code (API/socket)
- Orange: backend services
- Grey: external systems (Moodle, AI, storage)

- **Granularity rule (don’t overthink, split more)**:
- Page (`/login`, `/dashboard`, `/exams`) as its own node.
- Key component (`AlertPanel`, `VideoGrid`, etc.) as its own node.
- Integration client (`api.ts`, `socket.ts`) as its own node.

##### Frontend components
- Routes: LoginPage, DashboardPage, ExamsPage
- Layout: RootLayout
- Components: Navbar, AlertPanel, VideoGrid, StudentCard
- Services: api.ts, socket.ts, useSocket.ts
- Shared: constants.ts, student.ts

That combination will be detailed, honest about what’s actually in the repo, and still represent the full “moodle-proctor” system as it must exist in production.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =======================
  %% C4 L1: System Context
  %% =======================
  subgraph "C4 L1 — System Context (Moodle AI Proctoring)"
    direction TB

    Proctor["Proctor / Instructor"]:::person
    StudentUser["Student / Candidate"]:::person

    subgraph "moodle-proctor System"
      direction TB
      FrontendSystem["Next.js Frontend (This Repo)"]:::frontend
    end

    Moodle["Moodle LMS (External)"]:::external
    Backend["Proctoring Backend (External)"]:::backend
    Realtime["Realtime Server (WebSocket/Socket.IO) (External)"]:::backend
    AI["AI Proctoring Engine (External)"]:::external
    VideoSvc["Video Stream Source (Assumed WebRTC/Streaming) (External)"]:::external
    DB[("DB - Assumed")]:::datastore
    Storage[("Object Storage - Assumed")]:::datastore

    Proctor -->|"uses:UI_monitoring"| FrontendSystem
    StudentUser -->|"takes_exam:events/media"| Backend

    FrontendSystem -->|"REST/HTTP:exams,students,sessions,alerts"| Backend
    FrontendSystem <-->|"WSS:live_events,status,alerts"| Realtime

    Backend -->|"HTTPS:LTI/Plugin/API_integration"| Moodle
    Backend -->|"HTTP/gRPC:analysis,risk_scoring"| AI
    Backend -->|"persist:sessions,audit_logs"| DB
    Backend -->|"store:evidence,snapshots,clips"| Storage

    Backend -->|"issues_stream_tokens/urls"| VideoSvc
    FrontendSystem -->|"renders_live_tiles:stream_url/token"| VideoSvc
  end

  %% =======================
  %% C4 L2: Containers
  %% =======================
  subgraph "C4 L2 — Containers (Runtime / Deployable Units)"
    direction TB

    Browser["User Browser"]:::client

    subgraph "Frontend Container (In Repo)"
      direction TB
      NextApp["Next.js App Router (Node/Edge runtime)"]:::frontend
      Routes["Routes: /login • /dashboard • /exams"]:::frontend
      UI["UI Components"]:::frontend
      Clients["Integration Clients (API + Socket)"]:::integration
      Config["Config + Types"]:::shared
    end

    ApiContainer["API Backend (REST) (External)"]:::backend
    RtContainer["Realtime Gateway (WSS) (External)"]:::backend
    MoodleC["Moodle LMS (External)"]:::external
    AIC["AI Service (External)"]:::external
    DBC[("SQL DB - Assumed")]:::datastore
    Obj[("S3/Object Storage - Assumed")]:::datastore

    Browser -->|"HTTPS:page_load"| NextApp
    NextApp -->|"serves"| Routes
    Routes -->|"compose"| UI
    UI -->|"uses"| Clients
    Clients -->|"reads"| Config

    Browser -->|"HTTPS/JSON:api_calls"| ApiContainer
    Browser <-->|"WSS:realtime_events"| RtContainer

    ApiContainer -->|"HTTPS:integration"| MoodleC
    ApiContainer -->|"HTTP/gRPC:analysis"| AIC
    ApiContainer -->|"SQL:read/write"| DBC
    ApiContainer -->|"S3_API:artifacts"| Obj
  end

  %% =======================
  %% C4 L3: Frontend Components (Repo)
  %% =======================
  subgraph "C4 L3 — Frontend (Next.js App Router) Component View"
    direction TB

    subgraph "App Shell"
      direction TB
      NextConfig["Next.js Config"]:::shared
      RootLayout["RootLayout (global layout/providers)"]:::frontend
      GlobalCSS["globals.css (styles baseline)"]:::shared
      HomePage["HomePage (optional landing)"]:::frontend
    end

    subgraph "Route Pages"
      direction TB
      LoginPage["LoginPage (/login)"]:::frontend
      DashboardPage["DashboardPage (/dashboard)"]:::frontend
      ExamsPage["ExamsPage (/exams)"]:::frontend
    end

    subgraph "Reusable UI Components"
      direction TB
      Navbar["Navbar"]:::frontend
      AlertPanel["AlertPanel (proctoring alerts)"]:::frontend
      VideoGrid["VideoGrid (live tiles)"]:::frontend
      StudentCard["StudentCard (candidate status)"]:::frontend
    end

    subgraph "Client-side Integration"
      direction TB
      APIClient["API Client (REST/HTTP)"]:::integration
      SocketHook["useSocket Hook (connection lifecycle)"]:::integration
      SocketClient["Socket Client (WebSocket/Socket.IO)"]:::integration
    end

    subgraph "Shared Contracts"
      direction TB
      Constants["constants (API_BASE_URL,SOCKET_URL,...)"]:::shared
      StudentType["Student DTO/type"]:::shared
    end

    %% Composition
    RootLayout -->|"wraps"| HomePage
    RootLayout -->|"wraps"| LoginPage
    RootLayout -->|"wraps"| DashboardPage
    RootLayout -->|"wraps"| ExamsPage
    RootLayout -->|"includes"| Navbar
    RootLayout -->|"applies"| GlobalCSS

    DashboardPage -->|"uses"| AlertPanel
    DashboardPage -->|"uses"| VideoGrid
    DashboardPage -->|"uses"| StudentCard

    ExamsPage -->|"uses"| StudentCard
    ExamsPage -->|"uses"| VideoGrid

    %% Data + integration flows
    LoginPage -->|"auth:HTTP"| APIClient
    DashboardPage -->|"initial_load:HTTP"| APIClient
    ExamsPage -->|"fetch_exams/roster:HTTP"| APIClient

    DashboardPage -->|"subscribe:realtime"| SocketHook
    ExamsPage -->|"subscribe:realtime"| SocketHook
    SocketHook -->|"connect/manage"| SocketClient

    APIClient -->|"reads"| Constants
    SocketClient -->|"reads"| Constants

    APIClient -->|"returns:Student[]"| StudentType
    SocketClient -->|"events:studentStatus/alerts"| StudentType

    StudentType -->|"renders"| StudentCard
    StudentType -->|"renders"| VideoGrid
    SocketClient -->|"push_alerts"| AlertPanel
  end

  %% =======================
  %% Click Events (from mapping)
  %% =======================
  click NextConfig "https://github.com/cegit27/moodle-proctor/blob/main/frontend/next.config.ts"
  click RootLayout "https://github.com/cegit27/moodle-proctor/blob/main/frontend/app/layout.tsx"
  click GlobalCSS "https://github.com/cegit27/moodle-proctor/blob/main/frontend/app/globals.css"
  click HomePage "https://github.com/cegit27/moodle-proctor/blob/main/frontend/app/page.tsx"
  click LoginPage "https://github.com/cegit27/moodle-proctor/blob/main/frontend/app/login/page.tsx"
  click DashboardPage "https://github.com/cegit27/moodle-proctor/blob/main/frontend/app/dashboard/page.tsx"
  click ExamsPage "https://github.com/cegit27/moodle-proctor/blob/main/frontend/app/exams/page.tsx"
  click Navbar "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/components/Navbar.tsx"
  click AlertPanel "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/components/AlertPanel.tsx"
  click StudentCard "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/components/StudentCard.tsx"
  click VideoGrid "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/components/VideoGrid.tsx"
  click APIClient "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/services/api.ts"
  click SocketClient "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/services/socket.ts"
  click SocketHook "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/hooks/useSocket.ts"
  click Constants "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/utils/constants.ts"
  click StudentType "https://github.com/cegit27/moodle-proctor/blob/main/frontend/src/types/student.ts"

  %% =======================
  %% Styles
  %% =======================
  classDef person fill:#E6F4FF,stroke:#1D4ED8,stroke-width:1.5px,color:#0B1220;
  classDef client fill:#DBEAFE,stroke:#2563EB,stroke-width:1.5px,color:#0B1220;

  classDef frontend fill:#CFFAFE,stroke:#0891B2,stroke-width:1.5px,color:#0B1220;
  classDef integration fill:#E9D5FF,stroke:#7C3AED,stroke-width:1.5px,color:#0B1220;
  classDef shared fill:#E5E7EB,stroke:#6B7280,stroke-width:1.5px,color:#0B1220;

  classDef backend fill:#FFEDD5,stroke:#EA580C,stroke-width:1.5px,color:#0B1220;
  classDef external fill:#F3F4F6,stroke:#9CA3AF,stroke-width:1.5px,color:#0B1220,stroke-dasharray: 5 5;

  classDef datastore fill:#FEF9C3,stroke:#CA8A04,stroke-width:1.5px,color:#0B1220;
```
