# newer1107/emqpgs architecture

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

- Interactive diagram: https://gitdiagram.com/newer1107/emqpgs
- Repository: https://github.com/newer1107/emqpgs

## Overview

EMQPGS manages examination question-paper production from academic setup and question contribution through moderation, bank approval, analysis, paper generation, dean selection, and COE export. Users enter through a responsibility-scoped workspace; the application exposes role-specific dashboards and API routes, with domain services backed by Prisma and MySQL. Optional AI analysis and MinIO-backed document storage support the workflow. The README documents the major flow and layering; sampled source confirms selected evaluation, storage, readiness, and dean-review behavior, but not every route-to-service connection.

Main entry points: [`app/api/question-banks/[id]/route.ts`](https://github.com/newer1107/emqpgs/blob/main/app/api/question-banks/%5Bid%5D/route.ts) (API routes), [`src/modules`](https://github.com/newer1107/emqpgs/tree/main/src/modules) (Domain services), [`src/modules/production/dean-review.service.ts`](https://github.com/newer1107/emqpgs/blob/main/src/modules/production/dean-review.service.ts) (Dean review), [`src/lib/storage/storage-service.ts`](https://github.com/newer1107/emqpgs/blob/main/src/lib/storage/storage-service.ts) (Object storage service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and Workspaces"]
  node_login["Login<br/>[page.tsx]"]
  node_workspace["Workspace selection<br/>[page.tsx]"]
  node_authz["Authorization"]
end

subgraph group_academic["Academic Setup"]
  node_academic_ui["Academic setup<br/>[page.tsx]"]
  node_curriculum["Curriculum and subjects<br/>[page.tsx]"]
  node_exam_cycles["Exam cycles<br/>[page.tsx]"]
end

subgraph group_bank["Question Bank Workflow"]
  node_contributor["Question contribution<br/>[page.tsx]"]
  node_moderation["Question moderation<br/>[page.tsx]"]
  node_bank_lifecycle["Bank lifecycle<br/>[service.ts]"]
  node_readiness["Phase readiness<br/>[engine.ts]"]
  node_audit["Bank audit<br/>[service.ts]"]
end

subgraph group_papers["Analysis and Production"]
  node_analysis_ui["Bank analysis<br/>[page.tsx]"]
  node_analysis["Analysis engine<br/>[analysis-engine.ts]"]
  node_ai_analysis["Optional AI analysis"]
  node_generation["Paper generation"]
  node_paper_evaluation["Variant scoring"]
  node_dean["Dean review"]
  node_export["Exports<br/>[export.service.ts]"]
end

subgraph group_platform["Services and Data"]
  node_api["API routes<br/>[route.ts]"]
  node_domain_services["Domain services"]
  node_database[("MySQL via Prisma<br/>[db.ts]")]
  node_storage_service["Object storage service<br/>[storage-service.ts]"]
  node_minio[("MinIO object store")]
end

node_user(("Academic user"))
node_ollama{{"Ollama"}}

node_user -->|"signs in"| node_login
node_login -->|"selects context"| node_workspace
node_workspace -->|"sets scope"| node_authz
node_user -->|"manages setup"| node_academic_ui
node_user -->|"manages subjects"| node_curriculum
node_user -->|"submits questions"| node_contributor
node_user -->|"reviews questions"| node_moderation
node_user -->|"analyzes banks"| node_analysis_ui
node_user -->|"reviews variants"| node_dean
node_academic_ui -->|"requests data"| node_api
node_curriculum -->|"requests data"| node_api
node_exam_cycles -->|"requests data"| node_api
node_contributor -->|"submits questions"| node_api
node_moderation -->|"sends decisions"| node_api
node_analysis_ui -->|"requests analysis"| node_api
node_dean -->|"submits selection"| node_api
node_export -->|"serves downloads"| node_api
node_api -->|"checks permissions"| node_authz
node_api -->|"dispatches requests"| node_domain_services
node_domain_services -->|"reads and writes"| node_database
node_domain_services -->|"manages banks"| node_bank_lifecycle
node_bank_lifecycle -->|"checks phase readiness"| node_readiness
node_domain_services -->|"runs bank audits"| node_audit
node_domain_services -->|"builds analysis"| node_analysis
node_analysis -.->|"adds AI interpretation"| node_ai_analysis
node_ai_analysis -.->|"requests AI output"| node_ollama
node_domain_services -->|"generates variants"| node_generation
node_generation -->|"scores assignments"| node_paper_evaluation
node_domain_services -->|"submits review"| node_dean
node_dean -->|"stores selection"| node_database
node_domain_services -->|"creates export packets"| node_export
node_storage_service -->|"records assets"| node_database
node_storage_service -->|"stores objects"| node_minio
node_generation -->|"stores generated papers"| node_storage_service
node_export -->|"stores export files"| node_storage_service

click node_login "https://github.com/newer1107/emqpgs/blob/main/app/login/page.tsx"
click node_workspace "https://github.com/newer1107/emqpgs/blob/main/app/(auth)/workspace-select/page.tsx"
click node_authz "https://github.com/newer1107/emqpgs/blob/main/src/lib/auth/authorization-service.ts"
click node_academic_ui "https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coe/academic-setup/page.tsx"
click node_curriculum "https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coordinator/subjects/page.tsx"
click node_exam_cycles "https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coe/exam-cycles/page.tsx"
click node_contributor "https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/contributor/submit-question/page.tsx"
click node_moderation "https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/moderator/questions/page.tsx"
click node_bank_lifecycle "https://github.com/newer1107/emqpgs/blob/main/src/modules/question-banks/service.ts"
click node_readiness "https://github.com/newer1107/emqpgs/blob/main/src/modules/readiness/engine.ts"
click node_audit "https://github.com/newer1107/emqpgs/blob/main/src/modules/qb-audit/service.ts"
click node_analysis_ui "https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coordinator/analysis/page.tsx"
click node_analysis "https://github.com/newer1107/emqpgs/blob/main/src/modules/reports/analysis-engine.ts"
click node_ai_analysis "https://github.com/newer1107/emqpgs/blob/main/src/modules/reports/ai-report.service.ts"
click node_generation "https://github.com/newer1107/emqpgs/blob/main/src/modules/paper-generation-engine/paper-generation-engine.ts"
click node_paper_evaluation "https://github.com/newer1107/emqpgs/blob/main/src/modules/paper-generation-engine/evaluation-engine.ts"
click node_dean "https://github.com/newer1107/emqpgs/blob/main/src/modules/production/dean-review.service.ts"
click node_export "https://github.com/newer1107/emqpgs/blob/main/src/modules/production/export.service.ts"
click node_api "https://github.com/newer1107/emqpgs/blob/main/app/api/question-banks/%5Bid%5D/route.ts"
click node_domain_services "https://github.com/newer1107/emqpgs/tree/main/src/modules"
click node_database "https://github.com/newer1107/emqpgs/blob/main/src/lib/db.ts"
click node_storage_service "https://github.com/newer1107/emqpgs/blob/main/src/lib/storage/storage-service.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_login,node_workspace,node_authz,node_user toneBlue
class node_academic_ui,node_curriculum,node_exam_cycles toneAmber
class node_contributor,node_moderation,node_bank_lifecycle,node_readiness,node_audit toneMint
class node_analysis_ui,node_analysis,node_ai_analysis,node_generation,node_paper_evaluation,node_dean,node_export toneRose
class node_api,node_domain_services,node_database,node_storage_service,node_minio,node_ollama toneIndigo
```

## Components

### Access and Workspaces

- [Login](https://github.com/newer1107/emqpgs/blob/main/app/login/page.tsx): `app/login/page.tsx`
- [Workspace selection](https://github.com/newer1107/emqpgs/blob/main/app/(auth)/workspace-select/page.tsx): `app/(auth)/workspace-select/page.tsx`
- [Authorization](https://github.com/newer1107/emqpgs/blob/main/src/lib/auth/authorization-service.ts): `src/lib/auth/authorization-service.ts`

### Academic Setup

- [Academic setup](https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coe/academic-setup/page.tsx): `app/(protected)/dashboard/coe/academic-setup/page.tsx`
- [Curriculum and subjects](https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coordinator/subjects/page.tsx): `app/(protected)/dashboard/coordinator/subjects/page.tsx`
- [Exam cycles](https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coe/exam-cycles/page.tsx): `app/(protected)/dashboard/coe/exam-cycles/page.tsx`

### Question Bank Workflow

- [Question contribution](https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/contributor/submit-question/page.tsx): `app/(protected)/dashboard/contributor/submit-question/page.tsx`
- [Question moderation](https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/moderator/questions/page.tsx): `app/(protected)/dashboard/moderator/questions/page.tsx`
- [Bank lifecycle](https://github.com/newer1107/emqpgs/blob/main/src/modules/question-banks/service.ts): `src/modules/question-banks/service.ts`
- [Phase readiness](https://github.com/newer1107/emqpgs/blob/main/src/modules/readiness/engine.ts): `src/modules/readiness/engine.ts`
- [Bank audit](https://github.com/newer1107/emqpgs/blob/main/src/modules/qb-audit/service.ts): `src/modules/qb-audit/service.ts`

### Analysis and Production

- [Bank analysis](https://github.com/newer1107/emqpgs/blob/main/app/(protected)/dashboard/coordinator/analysis/page.tsx): `app/(protected)/dashboard/coordinator/analysis/page.tsx`
- [Analysis engine](https://github.com/newer1107/emqpgs/blob/main/src/modules/reports/analysis-engine.ts): `src/modules/reports/analysis-engine.ts`
- [Optional AI analysis](https://github.com/newer1107/emqpgs/blob/main/src/modules/reports/ai-report.service.ts): `src/modules/reports/ai-report.service.ts`
- [Paper generation](https://github.com/newer1107/emqpgs/blob/main/src/modules/paper-generation-engine/paper-generation-engine.ts): `src/modules/paper-generation-engine/paper-generation-engine.ts`
- [Variant scoring](https://github.com/newer1107/emqpgs/blob/main/src/modules/paper-generation-engine/evaluation-engine.ts): `src/modules/paper-generation-engine/evaluation-engine.ts`
- [Dean review](https://github.com/newer1107/emqpgs/blob/main/src/modules/production/dean-review.service.ts): `src/modules/production/dean-review.service.ts`
- [Exports](https://github.com/newer1107/emqpgs/blob/main/src/modules/production/export.service.ts): `src/modules/production/export.service.ts`

### Services and Data

- [API routes](https://github.com/newer1107/emqpgs/blob/main/app/api/question-banks/%5Bid%5D/route.ts): `app/api/question-banks/[id]/route.ts`
- [Domain services](https://github.com/newer1107/emqpgs/tree/main/src/modules): `src/modules`
- [MySQL via Prisma](https://github.com/newer1107/emqpgs/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Object storage service](https://github.com/newer1107/emqpgs/blob/main/src/lib/storage/storage-service.ts): `src/lib/storage/storage-service.ts`
- **MinIO object store**

### Other components

- **Academic user**
- **Ollama**

## Connections

- Academic user → Login: signs in
- Login → Workspace selection: selects context
- Workspace selection → Authorization: sets scope
- Academic user → Academic setup: manages setup
- Academic user → Curriculum and subjects: manages subjects
- Academic user → Question contribution: submits questions
- Academic user → Question moderation: reviews questions
- Academic user → Bank analysis: analyzes banks
- Academic user → Dean review: reviews variants
- Academic setup → API routes: requests data
- Curriculum and subjects → API routes: requests data
- Exam cycles → API routes: requests data
- Question contribution → API routes: submits questions
- Question moderation → API routes: sends decisions
- Bank analysis → API routes: requests analysis
- Dean review → API routes: submits selection
- Exports → API routes: serves downloads
- API routes → Authorization: checks permissions
- API routes → Domain services: dispatches requests
- Domain services → MySQL via Prisma: reads and writes
- Domain services → Bank lifecycle: manages banks
- Bank lifecycle → Phase readiness: checks phase readiness
- Domain services → Bank audit: runs bank audits
- Domain services → Analysis engine: builds analysis
- Analysis engine → Optional AI analysis: adds AI interpretation
- Optional AI analysis → Ollama: requests AI output
- Domain services → Paper generation: generates variants
- Paper generation → Variant scoring: scores assignments
- Domain services → Dean review: submits review
- Dean review → MySQL via Prisma: stores selection
- Domain services → Exports: creates export packets
- Object storage service → MySQL via Prisma: records assets
- Object storage service → MinIO object store: stores objects
- Paper generation → Object storage service: stores generated papers
- Exports → Object storage service: stores export files