# preliminary-examinations-2025/bics-portal architecture

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

- Interactive diagram: https://gitdiagram.com/preliminary-examinations-2025/bics-portal
- Repository: https://github.com/preliminary-examinations-2025/bics-portal

## Overview

This repository implements a BICS academic portal with separate student/admin, online-exam, and Kata competitive-programming interfaces backed by one API. Students authenticate and use academic services, take monitored exams, and submit incident-review information; administrators manage institutional records and operations. Kata users register handles, participate in contests, submit solutions, and receive evaluations and ratings. The backend also processes lecture ingestion and EIRF follow-up asynchronously. Connections reflect shown imports, calls, or routes; unsampled route internals are not inferred.

Main entry points: [`backend/server.js`](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/server.js) (API server), [`frontend_ot/src/App.jsx`](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_ot/src/App.jsx) (Exam workflow), [`frontend_workspace/src/App.jsx`](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/App.jsx) (Kata workspace), [`backend/routes/auth.js`](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/auth.js) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Academic Portal"]
  node_student["Student interface<br/>[App.jsx]"]
  node_portal_api["Portal API client<br/>[client.js]"]
end

subgraph group_exam["Online Examination"]
  node_exam_ui["Exam workflow<br/>[App.jsx]"]
  node_exam_api["Exam API client<br/>[client.js]"]
end

subgraph group_kata["Kata Platform"]
  node_kata_ui["Kata workspace<br/>[App.jsx]"]
  node_kata_auth["Kata authentication<br/>[AuthContext.jsx]"]
  node_kata_api["Kata API client<br/>[kataApi.js]"]
end

subgraph group_backend["Backend Services"]
  node_server["API server<br/>[server.js]"]
  node_auth["Authentication<br/>[auth.js]"]
  node_exam_routes["Exam operations<br/>[tests.js]"]
  node_kata_routes["Kata operations<br/>[kata.js]"]
  node_judge["Solution judging<br/>[judgeEngine.js]"]
  node_kata_eval["AI evaluation<br/>[kataAiEvaluator.js]"]
  node_ratings["Contest ratings<br/>[ratingEngine.js]"]
  node_eirf_worker["EIRF pipeline"]
  node_lecture_worker["Lecture ingestion"]
  node_email["Email delivery"]
end

subgraph group_data["Persistence"]
  node_db_config["Database connection<br/>[db.js]"]
  node_candidate_data[("Candidate records<br/>[Candidate.js]")]
  node_exam_data[("Exam submissions<br/>[TestSubmission.js]")]
  node_kata_data[("Kata records<br/>[KataSubmission.js]")]
end

node_actor(("Portal users"))

node_actor -->|"uses"| node_student
node_student -->|"requests data"| node_portal_api
node_actor -->|"takes exams"| node_exam_ui
node_exam_ui -->|"reads responses"| node_exam_api
node_exam_ui -->|"submits exam data"| node_exam_routes
node_actor -->|"uses"| node_kata_ui
node_kata_ui -->|"provides session"| node_kata_auth
node_kata_auth -->|"requests account"| node_kata_api
node_kata_ui -.->|"requests Kata data"| node_kata_api
node_server -->|"mounts routes"| node_auth
node_server -->|"mounts routes"| node_exam_routes
node_server -->|"mounts routes"| node_kata_routes
node_auth -->|"reads records"| node_candidate_data
node_auth -->|"uses storage"| node_db_config
node_exam_routes -.->|"handles submissions"| node_exam_data
node_kata_routes -.->|"dispatches judging"| node_judge
node_judge -->|"delegates evaluation"| node_kata_eval
node_judge -->|"uses submissions"| node_kata_data
node_kata_eval -->|"reads submissions"| node_kata_data
node_ratings -.->|"rates contest entries"| node_kata_data
node_eirf_worker -.->|"processes incidents"| node_exam_data
node_eirf_worker -->|"dispatches email"| node_email
node_lecture_worker -->|"loads lecture data"| node_db_config
node_db_config -.->|"persists records"| node_candidate_data

click node_student "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend/src/App.jsx"
click node_portal_api "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend/src/api/client.js"
click node_exam_ui "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_ot/src/App.jsx"
click node_exam_api "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_ot/src/api/client.js"
click node_kata_ui "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/App.jsx"
click node_kata_auth "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/context/AuthContext.jsx"
click node_kata_api "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/utils/kataApi.js"
click node_server "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/server.js"
click node_auth "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/auth.js"
click node_exam_routes "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/tests.js"
click node_kata_routes "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/kata.js"
click node_judge "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/utils/judgeEngine.js"
click node_kata_eval "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/services/kataAiEvaluator.js"
click node_ratings "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/utils/ratingEngine.js"
click node_eirf_worker "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/workers/eirfPipelineWorker.js"
click node_lecture_worker "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/services/lectureIngestionWorker.js"
click node_email "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/services/gmailEmailService.js"
click node_db_config "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/config/db.js"
click node_candidate_data "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/models/Candidate.js"
click node_exam_data "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/models/TestSubmission.js"
click node_kata_data "https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/models/KataSubmission.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_student,node_portal_api,node_actor toneBlue
class node_exam_ui,node_exam_api toneAmber
class node_kata_ui,node_kata_auth,node_kata_api toneMint
class node_server,node_auth,node_exam_routes,node_kata_routes,node_judge,node_kata_eval,node_ratings,node_eirf_worker,node_lecture_worker,node_email toneRose
class node_db_config,node_candidate_data,node_exam_data,node_kata_data toneIndigo
```

## Components

### Academic Portal

- [Student interface](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Portal API client](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Online Examination

- [Exam workflow](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_ot/src/App.jsx): `frontend_ot/src/App.jsx`
- [Exam API client](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_ot/src/api/client.js): `frontend_ot/src/api/client.js`

### Kata Platform

- [Kata workspace](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/App.jsx): `frontend_workspace/src/App.jsx`
- [Kata authentication](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/context/AuthContext.jsx): `frontend_workspace/src/context/AuthContext.jsx`
- [Kata API client](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/frontend_workspace/src/utils/kataApi.js): `frontend_workspace/src/utils/kataApi.js`

### Backend Services

- [API server](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/server.js): `backend/server.js`
- [Authentication](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Exam operations](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/tests.js): `backend/routes/tests.js`
- [Kata operations](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/routes/kata.js): `backend/routes/kata.js`
- [Solution judging](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/utils/judgeEngine.js): `backend/utils/judgeEngine.js`
- [AI evaluation](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/services/kataAiEvaluator.js): `backend/services/kataAiEvaluator.js`
- [Contest ratings](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/utils/ratingEngine.js): `backend/utils/ratingEngine.js`
- [EIRF pipeline](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/workers/eirfPipelineWorker.js): `backend/workers/eirfPipelineWorker.js`
- [Lecture ingestion](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/services/lectureIngestionWorker.js): `backend/services/lectureIngestionWorker.js`
- [Email delivery](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/services/gmailEmailService.js): `backend/services/gmailEmailService.js`

### Persistence

- [Database connection](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/config/db.js): `backend/config/db.js`
- [Candidate records](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/models/Candidate.js): `backend/models/Candidate.js`
- [Exam submissions](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/models/TestSubmission.js): `backend/models/TestSubmission.js`
- [Kata records](https://github.com/preliminary-examinations-2025/bics-portal/blob/main/backend/models/KataSubmission.js): `backend/models/KataSubmission.js`

### Other components

- **Portal users**

## Connections

- Portal users → Student interface: uses (evidence: `frontend/src/App.jsx`)
- Student interface → Portal API client: requests data (evidence: `frontend/src/App.jsx`)
- Portal users → Exam workflow: takes exams (evidence: `frontend_ot/src/App.jsx`)
- Exam workflow → Exam API client: reads responses (evidence: `frontend_ot/src/App.jsx`)
- Exam workflow → Exam operations: submits exam data (evidence: `frontend_ot/src/App.jsx`)
- Portal users → Kata workspace: uses (evidence: `frontend_workspace/src/App.jsx`)
- Kata workspace → Kata authentication: provides session (evidence: `frontend_workspace/src/App.jsx`)
- Kata authentication → Kata API client: requests account (evidence: `frontend_workspace/src/context/AuthContext.jsx`)
- Kata workspace → Kata API client: requests Kata data (evidence: `frontend_workspace/src/App.jsx`)
- API server → Authentication: mounts routes (evidence: `backend/server.js`)
- API server → Exam operations: mounts routes (evidence: `backend/server.js`)
- API server → Kata operations: mounts routes (evidence: `backend/server.js`)
- Authentication → Candidate records: reads records (evidence: `backend/routes/auth.js`)
- Authentication → Database connection: uses storage (evidence: `backend/routes/auth.js`)
- Exam operations → Exam submissions: handles submissions
- Kata operations → Solution judging: dispatches judging
- Solution judging → AI evaluation: delegates evaluation (evidence: `backend/utils/judgeEngine.js`)
- Solution judging → Kata records: uses submissions (evidence: `backend/utils/judgeEngine.js`)
- AI evaluation → Kata records: reads submissions (evidence: `backend/services/kataAiEvaluator.js`)
- Contest ratings → Kata records: rates contest entries
- EIRF pipeline → Exam submissions: processes incidents
- EIRF pipeline → Email delivery: dispatches email (evidence: `backend/workers/eirfPipelineWorker.js`)
- Lecture ingestion → Database connection: loads lecture data (evidence: `backend/services/lectureIngestionWorker.js`)
- Database connection → Candidate records: persists records