Overview
:::info Source
Sourced from services/assessment-service/SERVICE_OVERVIEW.md in the documentation repo.
:::
Bounded context: Assessment (Supporting domain) Companion docs: 03 Microservices · 02 DDD · 04 Events · 05 API Design Owners: Learning Delivery Guild (assessment squad) Status: Normative — v1.0
1. Mission
The assessment-service is the authoritative source of truth for quizzes, branching scenarios, question pools, grading rules, and learner attempt results on the Ghasi-edTech platform. It serves questions to the runtime player (via delivery-service), scores learner responses (deterministically or via AI grading), and emits scored attempt events that feed progress-service (the LRS), certification-service, and analytics-service.
The service sits at the midpoint of the learning value stream: authors create assessments in authoring-service; learners encounter them inside delivery-service; results become evidence inside progress-service. Assessment owns the correctness and high-trust scoring rules that all downstream services rely on.
2. Responsibilities
2.1 In scope (owned by this service)
- Quiz bank lifecycle — create, update, version, archive quiz banks and their questions.
- Question types — MCQ, multi-select, true/false, short answer, numeric answer, ordering, matching, hotspot, drag-drop-classify, Likert.
- Branching scenarios — directed-graph simulations with terminal outcomes and weighted scoring.
- Grading rules — per-question weight, per-bank pass threshold, penalty for wrong answers, partial credit, time-based penalties.
- Question pool randomization — deterministic-seeded shuffle of options and pool selection for serving to learners.
- Attempt scoring — authoritative server-side scoring (deterministic), with client-side scoring capability (offline) replayed and re-validated on reconnect.
- AI question generation — drafts of MCQ/scenario from lesson content via
ai-gateway-service(human approval required). - AI rubric grading — short-answer and open-ended grading with confidence score and mandatory human override path (high-risk AI per EU AI Act).
- Answer-key protection — encryption at rest with per-tenant KMS key; answer keys never leak into read replicas or logs.
- Anti-cheat primitives — time limits, navigation locks (one-way), randomized order, tamper-evident attempt envelopes.
- Attempt result immutability — once scored and closed, an
AttemptResultis append-only; re-grades create a newAttemptResultlinked byregradeOf.
2.2 Out of scope (belongs elsewhere)
| Concern | Owner |
|---|---|
| Storing learner progress / completion records | progress-service (LRS) |
| Storing course and lesson structure | authoring-service |
| Playing the quiz UI | delivery-service (player) |
| Storing media referenced by quiz prompts | media-service |
| Issuing certificates on pass | certification-service |
| Running the AI model | ai-gateway-service |
| Identity of the learner taking the attempt | identity-service |
3. Key collaborators
authoring-service ──(block.added kind=quiz)──▶ assessment-service
assessment-service ──(GET /quiz-banks/{id}/questions)──▶ delivery-service
delivery-service ──(POST /attempts/{id}/submit-response)──▶ assessment-service
assessment-service ──(attempt_result.scored.v1)──▶ progress-service
└──▶ analytics-service
└──▶ certification-service (via progress.completion.recorded)
ai-gateway-service ◀──(generate/grade request)── assessment-service
sync-service ──(offline attempt reconciliation)──▶ assessment-service
4. Architectural shape
- Runtime: Node.js 22 LTS, NestJS, TypeScript strict mode.
- Layering: Clean Architecture (Presentation → Application → Domain → Infrastructure) per doc 01 §2.
- Persistence: Postgres 16, schema
assessment, RLS on every table; pgvector optional for AI embedding search over question banks. - Events: NATS JetStream stream
ASSESSMENT, outbox-based publication, inbox-based consumption. - AI surface: never calls model providers directly; always routes through ai-gateway-service.
- Offline surface: exposes a
PlayPackageBundlecontribution adapter that emits encrypted quiz-bank payloads for client-side scoring.
5. Data sensitivity classification
| Data class | Examples | Handling |
|---|---|---|
| Secret | Answer keys, correct-answer flags, rubric texts | Encrypted at rest with per-tenant envelope key; never logged; never in read-replica projections |
| Confidential | Attempt responses, per-learner scores | RLS tenant-scoped; pseudonymized in analytics; retained per regulated class (180d hot / 7y cold) |
| Internal | Question prompts, quiz bank metadata | RLS tenant-scoped |
| Public | Question-bank counts aggregated across tenants (only for internal benchmarking, never exported) | — |
6. Non-functional targets (summary)
| Signal | Target |
|---|---|
p95 GET /quiz-banks/{id}/questions | < 150 ms |
p99 POST /attempts/{id}/score | < 350 ms (deterministic) / < 2.5 s (AI rubric) |
| Availability | 99.9% monthly |
| Scoring correctness on golden set | 100% deterministic; ≥ 95% AI rubric agreement with human raters |
| Event publication lag (outbox → consumer) | p95 < 1 s |
Full SLO table in OBSERVABILITY.md.
7. Roadmap posture (at a glance)
| Milestone | Target level | Headline scope |
|---|---|---|
| M0 / S0 | L1 (skeleton) | Scaffold, domain types, empty ports |
| M1 / S1 | L3 (customer MVP) | Basic quizzes (MCQ + T/F + short answer), deterministic scoring, player integration |
| M2 / S2-3 | L3 | + matching / ordering / hotspot; AI question draft (author-facing only) |
| M3 / S4 | L4 (feature complete) | + branching scenarios, SCORM 2004 scoring, xAPI emission, full anti-cheat |
| M4 / S5 | L4 | + AI rubric grading (HITL gated), distractor quality analysis |
| M5 / S6 | L4 | + psychometrics (IRT), adaptive difficulty |
See SERVICE_READINESS.md for the gate-level checklist.
8. Design principles specific to assessment
- Answer keys never travel further than they must. Even within the service, answer data is fetched through a
GradingContextport so that read paths for serving questions to learners cannot accidentally return correct-answer flags. - Scoring is a pure function of (responses, gradingRule). All side-effects (persisting the result, emitting the event) happen outside the scoring function, so scoring is trivially replayable, unit-testable, and deterministic across client and server.
- Offline scoring and server scoring must agree. If they disagree, the server score wins, and the mismatch is logged for human review. The service never silently accepts a client score.
- AI grading is high-risk. All AI-graded attempts carry
aiProvenance, a confidence score, and are routed to a human-review queue below a configured threshold. The learner-facing surface must indicate provisional status. - Regrades are new events. No mutation of historical
AttemptResult. A regrade is a new aggregate instance withregradeOflinkage; progress-service receives both events and applies policy about which supersedes.
9. Glossary (service-local terms)
| Term | Definition |
|---|---|
| Quiz bank | Container of questions plus a grading rule. Referenced by authoring blocks of kind quiz. |
| Question pool | Subset selected at serve time from a quiz bank (e.g., pick 10 of 50, randomized). |
| Branching scenario | Directed acyclic graph of decision nodes with terminal outcomes. |
| Attempt | A single learner's single run through a quiz or scenario. |
| AttemptResult | Immutable scored outcome of an attempt. |
| Grading rule | Declarative ruleset: per-question weight, pass threshold, penalty, partial credit, time limit. |
| Presentation form | Quiz payload with answer keys stripped — the shape served to the player. |
| Rubric | Structured criteria used by AI grading for open-ended responses. |
10. Non-goals (intentionally unsupported)
- Not an authoring UI. The authoring-service owns the authoring experience; assessment-service is headless and consumed by it.
- Not a gradebook. progress-service aggregates across attempts, courses, and learners; assessment-service only scores individual attempts.
- Not a proctoring service. Proctoring (live camera, ID checks) is a separate future service; assessment-service only owns mechanical anti-cheat (timers, randomization).
- Not an adaptive-learning engine. Adaptive path selection lives in delivery-service; assessment-service can emit signals (difficulty, discrimination) that fuel it.