0%
balqalam Logo
balqalam
FeaturesCommunityPricingDocumentation
Login
  • Introduction
  • Pitch
  • Hogwarts
  • Live Demo
  • MVP
  • Roadmap
  • Launch Sprint
  • PRD
  • Get Started
  • Localhost
  • Architecture
  • Structure
  • Pattern
  • Page
  • Layout
  • Content
  • Types
  • Config
  • Actions
  • Queries
  • Authorization
  • Validation
  • Form
  • Table
  • Detail
  • Card
  • Util
  • Hooks
  • List Params
  • Views
  • README.md
  • ISSUE.md
  • Technology Stack
  • Database
  • File
  • CDN Assets
  • Entry Points
  • Dashboard
  • Authentication
  • Credentials
  • OAuth
  • Flow Diagrams
  • Multi-Tenancy
  • Offline
  • Onboarding
  • Onboarding Videos
  • Add Values
  • Admission
  • Application
  • Attendance
  • Compliance
  • Profile
  • Exams
  • Exam Wizard
  • Timetable
  • Classrooms
  • Notifications
  • Conference
  • LMS (Lumos)
Finance
  • Finance
  • Fee Management
  • Invoice
  • Wallet
  • Salary
  • Payroll
  • Timesheet
  • Expenses
  • Budget
  • Receipt
  • Accounts
  • Banking
  • Reports
  • Dashboard
  • Permissions
  • Messages
  • Integration Flow
  • Provision
  • AI Document Processing
  • Document Intelligence
  • Internationalization
  • Translation
  • Translation Guide
  • Icons
  • Docs Factory
  • Inspiration
  • Listings
  • Teachers
  • Students
  • Catalog
  • Library
  • Contributing
  • Code of conduct
  • GitHub Workflow
  • Database Seeds
  • Database Safety
  • Test Accounts
  • Playwright
  • Prettier
  • Block Rebound
Sales & GTM
  • Marketing Brief
  • Sales
  • Go-to-market
  • Marketing
  • Admission — Feature Spotlight
  • Pilot Program
  • Leads
  • Proposal
  • Outreach Templates
  • Case Study
  • Competitors
  • Landing-page teardown
  • Competitor FAQ
  • Business model
  • Shared economy
  • Traction
Fundraising & Ecosystem
  • Get Support
  • Investor Deck
  • Data Room
  • Investors
  • Accelerators
  • Incubators
  • Grants
  • Sponsors
  • Partners
  • Competitions & Hackathons
  • Universities & Training Centers

Exam Wizard

PreviousNext

Two wizard systems — Exam (template + generation) and Certificate (template + issuance) — with shared infrastructure and state management.

Two wizard systems, each in two phases. Phase 1 designs a template; Phase 2 consumes that template to produce instances.

SystemPhase 1Phase 2
Exam WizardTemplate — saves ExamTemplateGenerate — saves GeneratedExam + ExamPaperConfig + Exam
Certificate WizardTemplate — saves ExamCertificateConfigIssue — saves ExamCertificate (single / batch)

Auth: ADMIN, DEVELOPER, TEACHER only.

Routes

PhaseURLPurpose
Exam P1/{lang}/exams/generate/template-wizardNew exam template
Exam P1/{lang}/exams/generate/template-wizard/{configId}Edit exam template
Exam P2/{lang}/exams/generate/exam-wizardGenerate exam from template
Cert P1/{lang}/exams/certificates/cert-wizardNew cert template
Cert P1/{lang}/exams/certificates/cert-wizard/{configId}Edit cert template
Cert P2/{lang}/exams/certificatesManage + issue certs
Cert P2/{lang}/exams/certificates/verify/{code}Public verification

Phase 1 + Exam P2 use the (exam-wizard)/ route group (full-screen, no dashboard chrome). Cert P2 lives in (school-dashboard)/.

Wizard steps

Exam P1 — template (dynamic count)

#StepDescription
1galleryRegional preset (SD, SA, US, MENA) or blank
2infoName, subjects, grades, exam type, duration, marks, question types
3layout6 slots: header, studentInfo, instructions, answerSheet, cover, footer
4+question-{type}Dynamic — one per Q type, difficulty distribution
N-2scoringPassing score, grade boundaries (add / remove / reset)
N-1footer-printFooter variant + decorations (accent bar / watermark / frame) + print
Npreview4 summary cards + paper mockup + save (creates / updates ExamTemplate)

Exam P2 — generation (fixed 5)

#StepDescription
1templatePick from school's saved templates
2examNew exam form or pick existing PLANNED exam
3questionsAuto-fill matching questions + manual select with filters
4paper-configStyle, page size, versions (1-5), toggles
5previewSummary + generate (creates GeneratedExam + ExamPaperConfig in transaction)

Cert P1 — template (fixed 12)

#StepVariants / fields
1galleryRegional preset
2infoName, type (6), theme, bilingual title / body, eligibility, signatures
3headercrest / ministry / bilingual / minimal
4titleelegant / modern / classic / arabic-calligraphy
5recipientcentered / underline / framed / photo
6bodyachievement / report-summary / transcript / custom
7scoresbadge-row / table-grid / gauge / hidden
8signaturesdual / triple / single / stamps
9footerverification / minimal / dated / numbered
10decorations5 toggles — border, corners, seal, watermark, ribbon
11printA4 / Letter, landscape / portrait
12previewSummary + full mockup + save (creates / updates ExamCertificateConfig)

Cert P2 — issuance (dashboard, not wizard)

  • Single — generateCertificate(): eligibility check, rank calculation, verification code
  • Batch — batchGenerateCertificates() via BatchIssueDialog
  • Share — shareCertificate() returns public token
  • Verify — verifyCertificate() (public, no auth)
  • Revoke — revokeCertificate() soft revoke with reason

State

All Phase 1 wizards use useReducer + localStorage draft persistence + draft resume dialog + Context provider.

WizardStateActionsContextStorage key
Exam P1TemplateWizardState18WizardProvider / useWizard()wizard-template-{schoolId}
Exam P2ExamWizardState10None (self-contained)None
Cert P1CertWizardState17CertWizardProvider / useCertWizard()cert-wizard-{schoolId}

Shared infrastructure

ComponentUsed by
WizardShellExam P1, Cert P1
WizardCardAll wizards
VariantThumbnailExam P1, Cert P1
GalleryCardExam P1, Cert P1
GradeRowExam P1
MiniPaperMockup / Full…Exam P1
MiniCertMockup / Full…Cert P1
CertSlotStepCert P1 (7 slot steps delegate to this)

Exam P2 has its own inline shell — does NOT use WizardShell.

Prisma models

ModelFileCreated byPurpose
ExamTemplateqbank.prismaExam P1Template composition (blockConfig, scoringConfig, printConfig)
GeneratedExamqbank.prismaExam P2Generated paper from template
GeneratedExamQuestionqbank.prismaExam P2Question selection
ExamPaperConfigexam.prismaExam P2Print / layout (template style, page size, versions)
ExamCertificateConfigexam.prismaCert P1Cert template (compositionConfig, text, signatures)
ExamCertificateexam.prismaCert P2Issued cert (number, score, grade, share token)

Server actions

ActionFilePhaseCreates
saveTemplatewizard/template-wizard/actions.tsExam P1ExamTemplate
createExamFromWizardwizard/exam-wizard/actions.tsExam P2Exam + GeneratedExam + ExamPaperConfig (transaction)
saveCertificateCompositionwizard/cert-wizard/actions.tsCert P1ExamCertificateConfig
generateCertificatecertificates/actions/index.tsCert P2ExamCertificate (single)
batchGenerateCertificatescertificates/actions/index.tsCert P2ExamCertificate[] (batch)
shareCertificatecertificates/actions/index.tsCert P2Updates share token
verifyCertificatecertificates/actions/index.tsCert P2Read-only verification
revokeCertificatecertificates/actions/index.tsCert P2Soft revoke

File tree

Routes under src/app/[lang]/s/[subdomain]/(exam-wizard)/:

layout.tsx                                # Auth guard, full-screen <main>
exams/generate/
  template-wizard/page.tsx                # Exam P1 (new) → TemplateWizardClient
  template-wizard/[configId]/page.tsx     # Exam P1 (edit)
  exam-wizard/page.tsx                    # Exam P2 → ExamWizardClient
exams/certificates/
  cert-wizard/page.tsx                    # Cert P1 (new) → CertWizardClient
  cert-wizard/[configId]/page.tsx         # Cert P1 (edit)

Cert P2 in (school-dashboard)/exams/certificates/ — page.tsx, configs/, verify/[code]/page.tsx.

Components under src/components/school-dashboard/exams/wizard/:

types.ts                              # TemplateWizardState, WizardAction, StepDefinition
context/wizard-provider.tsx           # WizardProvider + useWizard()
layout/wizard-shell.tsx               # Top bar, sidebar nav, progress, prev / next
hooks/use-wizard-state.ts             # useReducer + localStorage
hooks/use-wizard-steps.ts             # Dynamic step list
atoms/                                # WizardCard, VariantThumbnail, GalleryCard, GradeRow, mockups

template-wizard/                      # Exam P1 — client + actions + 8 steps
exam-wizard/                          # Exam P2 — types, hooks, actions, client + 5 steps
cert-wizard/                          # Cert P1 — types, actions, client + provider + shell + atoms + 12 steps

Cert P2 components: src/components/school-dashboard/exams/certificates/ — content.tsx, config-list.tsx, config-form.tsx, certificate-list.tsx, batch-issue-dialog.tsx, validation.ts, actions/ (12 server actions).

Cross-module imports

  • Exam P1 — composition types from exams/templates/ (VARIANT_REGISTRY, region presets SD_NATIONAL, SA_NATIONAL, US_STANDARD, MENA_PRIVATE).
  • Cert P1 — composition types from grades/templates/composition/ (CERT_VARIANT_REGISTRY, cert region presets).
  • Both Phase 1 wizards share atoms (WizardCard, VariantThumbnail, GalleryCard).
  • Cert P2 is independent — only consumes ExamCertificateConfig from DB.

See also

  • Exams — full exam lifecycle
  • Pattern — wizard infrastructure conventions
ExamsTimetable

On This Page

RoutesWizard stepsExam P1 — template (dynamic count)Exam P2 — generation (fixed 5)Cert P1 — template (fixed 12)Cert P2 — issuance (dashboard, not wizard)StateShared infrastructurePrisma modelsServer actionsFile treeCross-module importsSee also

Built by Databayt ·

Welcome to balqalam.

A great journey is about to begin.