# abdulwedud33/entrance_self_test architecture

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

- Interactive diagram: https://gitdiagram.com/abdulwedud33/entrance_self_test
- Repository: https://github.com/abdulwedud33/entrance_self_test

## Overview

This is a Grade 12 entrance-exam self-test system: students authenticate, choose an eligible subject and year, verify an exam password, answer questions, and receive scored results with answer review. Admins manage users, subjects, questions, events, exam settings, feedback, and results; instructors manage subject-scoped questions and review results. The graph groups the Next.js portals, Express API domains, shared authorization, and persistence. Frontend-to-API links reflect documented product/API capabilities; unsampled page-level calls are not asserted.

Main entry points: [`backend/src/middleware/auth.middleware.ts`](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/middleware/auth.middleware.ts) (Role guards), [`backend/src/utils/prisma.ts`](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/utils/prisma.ts) (Prisma client), [`backend/src/index.ts`](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/index.ts) (Express server), [`frontend/src/lib/api.ts`](https://github.com/abdulwedud33/entrance_self_test/blob/main/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Web portals"]
  node_student_ui["Student portal"]
  node_exam_ui["Exam session<br/>[page.tsx]"]
  node_admin_ui["Admin console"]
  node_instructor_ui["Instructor portal"]
  node_frontend_api["API client<br/>[api.ts]"]
end

subgraph group_api["API domains"]
  node_server["Express server<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>[auth.routes.ts]"]
  node_admin_routes["Admin routes<br/>[admin.routes.ts]"]
  node_admin_logic["Administration"]
  node_exam_routes["Exam routes<br/>[exam.routes.ts]"]
  node_exam_logic["Exam workflow<br/>[exam.controller.ts]"]
  node_student_routes["Student routes<br/>[student.routes.ts]"]
  node_student_logic["Student services"]
  node_instructor_routes["Instructor routes"]
  node_instructor_logic["Instructor services"]
end

subgraph group_access["Identity and access"]
  node_auth_logic["Authentication<br/>[auth.controller.ts]"]
  node_auth_guard["Role guards<br/>[auth.middleware.ts]"]
  node_jwt["JWT helpers<br/>[jwt.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_client["Prisma client<br/>[prisma.ts]"]
  node_postgres[("PostgreSQL")]
end

node_student_actor(("Student"))
node_admin_actor(("Administrator"))
node_instructor_actor(("Instructor"))

node_student_actor -->|"uses portal"| node_student_ui
node_student_ui -.->|"requests data"| node_frontend_api
node_student_ui -.->|"opens exam"| node_exam_ui
node_exam_ui -.->|"submits answers"| node_frontend_api
node_admin_actor -->|"uses portal"| node_admin_ui
node_admin_ui -.->|"requests data"| node_frontend_api
node_instructor_actor -->|"uses portal"| node_instructor_ui
node_instructor_ui -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls API"| node_server
node_server -->|"mounts routes"| node_auth_routes
node_server -->|"mounts routes"| node_admin_routes
node_server -->|"mounts routes"| node_exam_routes
node_server -->|"mounts routes"| node_student_routes
node_server -->|"mounts routes"| node_instructor_routes
node_auth_routes -->|"dispatches"| node_auth_logic
node_auth_routes -->|"uses guard"| node_auth_guard
node_admin_routes -->|"dispatches"| node_admin_logic
node_admin_routes -->|"checks roles"| node_auth_guard
node_exam_routes -->|"dispatches"| node_exam_logic
node_exam_routes -->|"checks student"| node_auth_guard
node_student_routes -->|"dispatches"| node_student_logic
node_student_routes -->|"checks student"| node_auth_guard
node_instructor_routes -->|"dispatches"| node_instructor_logic
node_instructor_routes -->|"checks instructor"| node_auth_guard
node_auth_logic -->|"signs tokens"| node_jwt
node_auth_guard -->|"verifies tokens"| node_jwt
node_auth_logic -->|"reads accounts"| node_prisma_client
node_auth_guard -->|"loads scope"| node_prisma_client
node_admin_logic -->|"manages records"| node_prisma_client
node_exam_logic -->|"loads and saves"| node_prisma_client
node_student_logic -->|"reads and writes"| node_prisma_client
node_instructor_logic -->|"queries results"| node_prisma_client
node_prisma_client -->|"persists data"| node_postgres

click node_student_ui "https://github.com/abdulwedud33/entrance_self_test/tree/main/frontend/src/app/student"
click node_exam_ui "https://github.com/abdulwedud33/entrance_self_test/blob/main/frontend/src/app/student/exam/page.tsx"
click node_admin_ui "https://github.com/abdulwedud33/entrance_self_test/tree/main/frontend/src/app/admin"
click node_instructor_ui "https://github.com/abdulwedud33/entrance_self_test/tree/main/frontend/src/app/instructor"
click node_frontend_api "https://github.com/abdulwedud33/entrance_self_test/blob/main/frontend/src/lib/api.ts"
click node_server "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/index.ts"
click node_auth_routes "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/auth.routes.ts"
click node_auth_logic "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/auth.controller.ts"
click node_auth_guard "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/middleware/auth.middleware.ts"
click node_admin_routes "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/admin.routes.ts"
click node_admin_logic "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/admin.controller.ts"
click node_exam_routes "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/exam.routes.ts"
click node_exam_logic "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/exam.controller.ts"
click node_student_routes "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/student.routes.ts"
click node_student_logic "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/student.controller.ts"
click node_instructor_routes "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/instructor.routes.ts"
click node_instructor_logic "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/instructor.controller.ts"
click node_jwt "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/utils/jwt.ts"
click node_prisma_client "https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/utils/prisma.ts"

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_ui,node_exam_ui,node_admin_ui,node_instructor_ui,node_frontend_api toneBlue
class node_server,node_auth_routes,node_admin_routes,node_admin_logic,node_exam_routes,node_exam_logic,node_student_routes,node_student_logic,node_instructor_routes,node_instructor_logic toneAmber
class node_auth_logic,node_auth_guard,node_jwt toneMint
class node_prisma_client,node_postgres toneRose
class node_student_actor,node_admin_actor,node_instructor_actor toneIndigo
```

## Components

### Web portals

- [Student portal](https://github.com/abdulwedud33/entrance_self_test/tree/main/frontend/src/app/student): `frontend/src/app/student`
- [Exam session](https://github.com/abdulwedud33/entrance_self_test/blob/main/frontend/src/app/student/exam/page.tsx): `frontend/src/app/student/exam/page.tsx`
- [Admin console](https://github.com/abdulwedud33/entrance_self_test/tree/main/frontend/src/app/admin): `frontend/src/app/admin`
- [Instructor portal](https://github.com/abdulwedud33/entrance_self_test/tree/main/frontend/src/app/instructor): `frontend/src/app/instructor`
- [API client](https://github.com/abdulwedud33/entrance_self_test/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API domains

- [Express server](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Auth routes](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/auth.routes.ts): `backend/src/routes/auth.routes.ts`
- [Admin routes](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/admin.routes.ts): `backend/src/routes/admin.routes.ts`
- [Administration](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/admin.controller.ts): `backend/src/controllers/admin.controller.ts`
- [Exam routes](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/exam.routes.ts): `backend/src/routes/exam.routes.ts`
- [Exam workflow](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/exam.controller.ts): `backend/src/controllers/exam.controller.ts`
- [Student routes](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/student.routes.ts): `backend/src/routes/student.routes.ts`
- [Student services](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/student.controller.ts): `backend/src/controllers/student.controller.ts`
- [Instructor routes](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/routes/instructor.routes.ts): `backend/src/routes/instructor.routes.ts`
- [Instructor services](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/instructor.controller.ts): `backend/src/controllers/instructor.controller.ts`

### Identity and access

- [Authentication](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/controllers/auth.controller.ts): `backend/src/controllers/auth.controller.ts`
- [Role guards](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/middleware/auth.middleware.ts): `backend/src/middleware/auth.middleware.ts`
- [JWT helpers](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/utils/jwt.ts): `backend/src/utils/jwt.ts`

### Persistence

- [Prisma client](https://github.com/abdulwedud33/entrance_self_test/blob/main/backend/src/utils/prisma.ts): `backend/src/utils/prisma.ts`
- **PostgreSQL**

### Other components

- **Student**
- **Administrator**
- **Instructor**

## Connections

- Student → Student portal: uses portal
- Student portal → API client: requests data
- Student portal → Exam session: opens exam
- Exam session → API client: submits answers
- Administrator → Admin console: uses portal
- Admin console → API client: requests data
- Instructor → Instructor portal: uses portal
- Instructor portal → API client: requests data
- API client → Express server: calls API
- Express server → Auth routes: mounts routes (evidence: `backend/src/index.ts`)
- Express server → Admin routes: mounts routes (evidence: `backend/src/index.ts`)
- Express server → Exam routes: mounts routes (evidence: `backend/src/index.ts`)
- Express server → Student routes: mounts routes (evidence: `backend/src/index.ts`)
- Express server → Instructor routes: mounts routes (evidence: `backend/src/index.ts`)
- Auth routes → Authentication: dispatches (evidence: `backend/src/routes/auth.routes.ts`)
- Auth routes → Role guards: uses guard (evidence: `backend/src/routes/auth.routes.ts`)
- Admin routes → Administration: dispatches (evidence: `backend/src/routes/admin.routes.ts`)
- Admin routes → Role guards: checks roles (evidence: `backend/src/routes/admin.routes.ts`)
- Exam routes → Exam workflow: dispatches (evidence: `backend/src/routes/exam.routes.ts`)
- Exam routes → Role guards: checks student (evidence: `backend/src/routes/exam.routes.ts`)
- Student routes → Student services: dispatches (evidence: `backend/src/routes/student.routes.ts`)
- Student routes → Role guards: checks student (evidence: `backend/src/routes/student.routes.ts`)
- Instructor routes → Instructor services: dispatches (evidence: `backend/src/routes/instructor.routes.ts`)
- Instructor routes → Role guards: checks instructor (evidence: `backend/src/routes/instructor.routes.ts`)
- Authentication → JWT helpers: signs tokens (evidence: `backend/src/controllers/auth.controller.ts`)
- Role guards → JWT helpers: verifies tokens (evidence: `backend/src/middleware/auth.middleware.ts`)
- Authentication → Prisma client: reads accounts (evidence: `backend/src/controllers/auth.controller.ts`)
- Role guards → Prisma client: loads scope (evidence: `backend/src/middleware/auth.middleware.ts`)
- Administration → Prisma client: manages records (evidence: `backend/src/controllers/admin.controller.ts`)
- Exam workflow → Prisma client: loads and saves (evidence: `backend/src/controllers/exam.controller.ts`)
- Student services → Prisma client: reads and writes (evidence: `backend/src/controllers/student.controller.ts`)
- Instructor services → Prisma client: queries results (evidence: `backend/src/controllers/instructor.controller.ts`)
- Prisma client → PostgreSQL: persists data