Lay Preachers' Examination Preparation

A study and examination-preparation platform for the Methodist Church Ghana Connexional Lay Preachers' Examination, built around one principle:

Don't just tell the candidate whether they are right or wrong. Teach them why.

Every question in the bank carries the passage of the official syllabus its answer comes from, so getting something wrong sends you back to the exact paragraph rather than simply costing you a mark.

Part 2 is loaded and complete. The architecture is not built around one examination: adding Part 1, another Methodist Church Ghana examination, or an entirely different training programme means adding content, not changing code.

---

Contents

• What it does
• What is in the question bank
• Quick start
• Architecture
• Project structure
• Environment variables
• Database setup
• Seeding and content
• Creating an administrator
• Adding your own questions
• Theory marking
• Voice answers
• Testing
• Deployment
• Troubleshooting
• Honesty about the content

---

What it does

Study. The official syllabus, verbatim, organised into papers, chapters and topics with key points, key terms, scripture references and reading-time estimates. Mark a topic Not started, In progress, Completed or Needs revision; time spent reading is banked against it.

Practise. Quizzes you can aim at a paper, a chapter, a topic or a difficulty — or at your own history: questions you got wrong, questions from your weak areas, questions you have bookmarked, questions you have never seen. Every answer is followed immediately by the correct answer, the reason, the syllabus reference and any scripture.

Revise. A Leitner spaced-repetition scheme decides when a question comes back. Answer it right and it recedes; answer it wrong and it returns tomorrow. Daily Revision mixes previously missed questions, weak areas, questions falling due, and a few new ones.

Sit mock examinations. Timed papers in the real format — Section A objective and compulsory, Section B offering five theory questions of which three are answered. The clock runs on the server, so closing the tab does not pause it, and the paper submits itself when time runs out. Answers save as you go.

Answer theory questions by typing or by dictating them, and get them marked against the examiner's rubric criterion by criterion: what you covered, what you touched on, what you missed, and what a full-mark answer contains.

Track where you stand. A readiness score built from four measured components, an honest evidence cap so a handful of correct answers cannot make you look ready, weak and strong topics, accuracy trends, streaks, and recommendations that name the next thing to do and give you the button that starts it.

Administer. A content management system for questions, papers, topics, mock examinations and theory rubrics; bulk import with dry-run validation; user management; and analytics covering engagement, the hardest questions and the topics candidates struggle with most.

---

What is in the question bank

2,189 questions and 360 flashcards. Two kinds, always labelled as such in the interface.

Written from the syllabus

Paper	Objective	Theory	Flashcards
Old Testament Studies	88	13	59
New Testament Studies	99	14	65
Christian Doctrine	90	13	59
Liturgics	90	14	60
Methodist Studies	88	14	58
Church and Society	80	14	59
Total	535	82	360

Each carries a verbatim excerpt of the sentence that settles it, checked programmatically against the source text.

Transcribed from real past papers

Paper	2009	2010	2011	2012	2013	2014	2022	2023	2024	2025	Total
Christian Doctrine	-	27	56	31	57	65	33	31	27	27	354
Church and Society	-	-	87	-	50	62	32	32	32	31	326
New Testament Studies	-	-	30	12	31	23	-	29	34	43	202
Old Testament Studies	-	-	93	-	-	34	-	34	29	36	226
Liturgics	62	31	31	30	31	31	-	31	31	31	309
Methodist Studies	-	-	56	20	-	29	-	-	-	50	155

1,572 past-paper questions, including the supplied 2009-2014 papers and every paper already loaded through the September 2025 sitting. 434 are theory questions; 118 older past-paper theory questions retain full marking schemes.

665 past-paper answers have been traced to a syllabus passage. The other 907 are held at needs_review with no answer key, because the source paper has no key and the current syllabus does not settle the answer. Each records why in reviewNotes; these questions never appear in a quiz until a person confirms them. This is deliberate: the syllabus covers only its own commentary, so general knowledge is not used to manufacture an answer.

The supplied 2009-2014 source papers are preserved under data/part2/pastpapers/. Review-only transcriptions are generated into data/part2/gen/questions.*-past-review.json. The transcription rules are documented in docs/PAST_PAPER_TRANSCRIPTION.md.

The syllabus itself

Loaded in full and verbatim: 6 papers, 48 chapters, 317 topics, about 127,000 words, and 1,010 distinct scripture references indexed to the places that cite them.

Scripture

977 passages carry their actual text, in the Authorised (King James) Version — free of copyright, and the version the syllabus itself quotes. Each is stored verse by verse, so the scripture pages show numbered verses rather than a wall of prose, and the passage appears wherever a question cites it.

Six references carry no text because the syllabus mis-cites them — it asks for Malachi 5, and Malachi has four chapters. Those say so plainly rather than being quietly dropped.

Only the passages the syllabus cites are bundled, so there is no whole-Bible payload and no runtime dependency. To regenerate after adding content:

npm install kjv --no-save
node scripts/build-scripture-texts.mjs

---

Quick start

You need Node.js 18.17 or newer. You do not need to install MongoDB.

git clone <your-repository-url>
cd methodist-lay-preachers-prep

cp .env.example .env          # the defaults work as they are for local use

npm install                   # installs the API and the web client together
npm run seed                  # loads the syllabus, questions and mock exams
npm run dev                   # starts both servers

Then open http://localhost:5173.

Web client	http://localhost:5173
API	http://localhost:5000
API health check	http://localhost:5000/api/health

npm run dev runs the API and the web client together through concurrently, with output labelled api and web.

Register an account, choose Lay Preachers' Examination Part 2, set your examination date, and you are studying.

To get into the administration area, create an administrator:

npm run create:admin

---

Architecture

┌─────────────────────────┐         ┌──────────────────────────┐        ┌──────────────┐
│  Web client             │  REST   │  API                     │        │  MongoDB     │
│  React 18 · Vite        │────────▶│  Node · Express          │───────▶│  Mongoose    │
│  React Router · Tailwind│  JSON   │  JWT + refresh cookie    │        │              │
└─────────────────────────┘         └──────────────────────────┘        └──────────────┘
                                              │
                                              │ optional, server-side only
                                              ▼
                                    ┌──────────────────────────┐
                                    │  AI marking adapter      │
                                    │  (falls back to rubric)  │
                                    └──────────────────────────┘

Content model. Exam → Subject → Chapter → Topic, with Question attached at whichever level fits and every question carrying a manualReference back to a syllabus paragraph. Nothing is hard-coded to Part 2; the six papers are rows, not branches in the code.

Marking. Objective marking is one pure function (scoringService) returning the same shape for every question type, so no caller branches on type. Theory marking is a deterministic rubric engine with an optional AI adapter layered on top.

Progress. Every answer writes an immutable QuestionAttempt. Everything analytical is derived from that log, so no statistic can drift out of step with what actually happened. Two derived records sit alongside it: QuestionState (per-question Leitner box and revision priority) and StudyProgress (per-topic status and mastery).

Authentication. A short-lived access token in the Authorization header plus a long-lived refresh token in an httpOnly cookie that script cannot read. The refresh token carries a version claim; incrementing the user's tokenVersion signs them out everywhere at once.

For the full picture — database schema, API surface, scoring and readiness formulas, the theory marking pipeline and the content ingestion route — see docs/ARCHITECTURE.md.

---

Project structure

methodist-lay-preachers-prep/
├── backend/
│   ├── src/
│   │   ├── config/           env, database connection, logger
│   │   ├── controllers/      request handling, one file per area
│   │   ├── middleware/       auth, validation, rate limiting, errors
│   │   ├── models/           19 Mongoose schemas
│   │   ├── routes/           REST routing
│   │   ├── services/         the actual logic (see below)
│   │   ├── seed/             seeding, manual loading, import, admin creation
│   │   ├── utils/            errors, HTTP helpers, text and date helpers
│   │   └── validators/       Zod schemas for every request body
│   └── tests/                79 tests over the logic that decides marks
├── frontend/
│   └── src/
│       ├── components/       ui/ design system · quiz/ · dashboard/
│       ├── context/          authentication, toasts
│       ├── hooks/            async, countdown, speech recognition, storage
│       ├── layouts/          application shell, auth shell, examination shell
│       ├── pages/            34 screens, including admin/
│       ├── services/         the API client
│       └── utils/            formatting
├── shared/constants.js       vocabulary shared by both sides
├── data/part2/
│   ├── manual.json             the syllabus, parsed and verbatim
│   ├── questions.manual.json   2,189 questions
│   ├── flashcards.json         360 flashcards
│   ├── scripture-texts.json    977 passages, Authorised Version
│   ├── gen/                    per-paper source files
│   └── pastpapers/             extracted past-paper text, 2009-2025
├── scripts/
│   ├── ingest/                 syllabus and past-paper extraction (Python and JavaScript)
│   ├── content-generators/     the generators that produced data/part2/gen
│   ├── merge-content.mjs       merges gen/ into the seed files
│   ├── ingest/pastpaper-review.mjs  imports review-only historical papers
│   ├── verify-content.mjs      checks every citation against the syllabus
│   ├── shuffle-options.mjs     spreads correct answers across the options
│   ├── repair-excerpts.mjs     re-anchors citations that are not byte-exact
│   └── build-scripture-texts.mjs  resolves references to verse text
└── docs/

The services are where the thinking lives:

File	What it decides
scoringService.js	How every objective question type is marked
theory/rubricEngine.js	Criterion-by-criterion marking with no AI
theory/aiGrader.js	The optional AI adapter, and its guard rails
spacedRepetition.js	When a question comes back
progressService.js	Topic mastery, streaks, study time
adaptiveService.js	Readiness, recommendations, adaptive difficulty
quizService.js	Which questions a session gets
mockExamService.js	Sitting lifecycle, "answer three of five", marking
importService.js	Validating content before it can reach a candidate

---

Environment variables

Everything is documented inline in .env.example. The ones that matter:

Variable	Required	Notes
MONGODB_URI	in production	Empty locally starts an embedded MongoDB
JWT_ACCESS_SECRET	in production	≥ 16 characters; the server refuses to start without it
JWT_REFRESH_SECRET	in production	Must differ from the access secret
CORS_ORIGINS	in production	Comma-separated; must list your deployed web address exactly
TRUST_PROXY	behind a proxy	So rate limiting sees the real client address
AI_PROVIDER	no	none (default) or anthropic
ANTHROPIC_API_KEY	only with AI	Server-side only, never exposed to the browser
VITE_API_URL	in production	Your deployed API including /api

Generate a secret with:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

---

Database setup

Option 1 — nothing to install (default). Leave MONGODB_URI empty. On first run the server downloads and starts an embedded MongoDB, keeping its data in .data/mongodb, so your progress survives restarts. Best for studying on your own machine.

Option 2 — a local MongoDB. Install MongoDB Community Edition, then set:

MONGODB_URI=mongodb://127.0.0.1:27017/mlpp

Option 3 — MongoDB Atlas. Create a free M0 cluster, add a database user, allow your IP (or 0.0.0.0/0 for a hosted API), and set the connection string:

MONGODB_URI=mongodb+srv://USER:[email protected]/mlpp?retryWrites=true&w=majority

Required in production. The embedded database is refused there deliberately.

---

Seeding and content

npm run seed            # load everything; safe to run repeatedly
npm run seed:reset      # clear content first (never touches users or progress)

Seeding creates both examination stages, loads the syllabus into papers, chapters and topics, builds the scripture index, imports the questions and flashcards, and builds one mock examination per paper sized to the questions actually available.

Content lives in data/part2/ as plain JSON so it can be edited, reviewed in a pull request, and re-imported. After changing anything in data/part2/gen/:

node scripts/merge-content.mjs   # refuses to write on a duplicate id
npm run seed

To re-derive the syllabus from the source document (you supply the file):

python3 scripts/ingest/parse_syllabus.py path/to/syllabus.docx data/part2/manual.json

---

Creating an administrator

npm run create:admin

It prompts for a name, email and password so nothing ends up in your shell history. It will also promote and reset the password of an existing account, after confirming.

Alternatively set SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD before npm run seed.

---

Adding your own questions

Three routes, all reaching the same validator.

1. The admin editor. Administration → Questions → New question. Adapts to the question type, prefills the syllabus reference from the topic you choose, and shows a live preview of what a candidate sees before and after answering.

2. Bulk import in the interface. Administration → Import. Paste a JSON array, press Validate to dry-run it, read the per-row errors, then import.

3. The command line.

npm run import:content -- ./my-questions.json --dry-run
npm run import:content -- ./my-questions.json --publish

JSON and CSV are both accepted. In CSV, separate list values with | and use dotted headers (source.year) for nested fields.

A minimal record:

{
  "questionId": "DOC-O-1001",
  "examStage": "PART2",
  "subject": "DOC",
  "chapter": "THE DOCTRINE OF THE TRINITY",
  "topic": "1.2 Some Heresies (False Views about the Trinity)",
  "questionType": "multiple_choice",
  "question": "Which view holds that Father, Son and Spirit are three modes of one person?",
  "options": [
    { "key": "A", "text": "Modalism", "isCorrect": true },
    { "key": "B", "text": "Tri-theism", "isCorrect": false },
    { "key": "C", "text": "Arianism", "isCorrect": false },
    { "key": "D", "text": "Docetism", "isCorrect": false }
  ],
  "explanation": "Why this is the answer, in the syllabus's own terms.",
  "manualReference": { "excerpt": "The verbatim sentence that settles it." },
  "difficulty": "medium",
  "sourceKind": "manual_derived",
  "answerConfidence": "verified",
  "status": "published"
}

Subjects, chapters and topics are matched by title, so you never need a database id.

The validator refuses to publish a question that cannot teach anything: a published question must carry an explanation or a syllabus excerpt, and an objective question must have an answer key. A past-paper question imported without a key is kept, flagged unverified and held at needs_review — never quietly published.

Theory questions additionally take idealAnswer, keyPoints, marks and markingRubric. See docs/CONTENT_AUTHORING_BRIEF.md for the full field reference and the standard the existing bank was written to.

---

Theory marking

Two engines, in order of preference.

The rubric engine always runs. Each rubric criterion carries keywords and groups of synonyms; a criterion is covered when enough of its distinct ideas appear in the answer, half-covered when some do. It rewards the idea, not the vocabulary — a candidate who writes "affluence" scores the same as one who writes "prosperity" — and a length allowance stops a one-line answer stuffed with keywords from scoring like a full essay. No API key, no network, deterministic.

The AI adapter runs first when AI_PROVIDER=anthropic and a key is set. It is given only the question, the ideal answer, the rubric and the syllabus excerpt, and asked one thing: does the answer cover each criterion? It may not introduce doctrine, may not mark against anything but the supplied rubric, and must quote the candidate's own words as evidence — a criterion with no quotable evidence scores zero. Its arithmetic is recomputed server-side, and if it returns anything inconclusive the rubric result is used instead and the fact is recorded.

The candidate is never shown a mark that nothing stands behind.

---

Voice answers

Theory answers can be dictated using the browser's own speech recognition. Nothing is sent anywhere by the platform: the browser transcribes, the transcript is shown for editing, and only what the candidate accepts becomes the answer.

It works in Chrome and Edge, and in Safari on recent versions. Where it is unavailable — Firefox, most in-app browsers — the recording controls simply do not appear and typing is the whole interface. Microphone refusal, silence and network failures each get a message the candidate can act on.

---

Testing

npm test

79 tests over the parts where a mistake would quietly cost a candidate marks: objective marking of every question type including partial credit and typo tolerance, rubric marking and its length allowance, spaced-repetition priority, adaptive difficulty, streaks across month and year boundaries, readiness bands, token signing and expiry, role guards, and request validation.

They need no database.

---

Deployment

The intended shape is Vercel or Netlify for the web client, Render for the API, MongoDB Atlas for the database. Full step-by-step instructions, including the CORS and cookie settings that catch people out, are in docs/DEPLOYMENT.md.

The short version:

API on Render — root directory backend, build npm install, start npm start. Set NODE_ENV=production, MONGODB_URI, both JWT secrets, CORS_ORIGINS (your web address), and TRUST_PROXY=true.

Web client on Vercel — build npm run build, output frontend/dist. Set VITE_API_URL=https://your-api.onrender.com/api. Add a rewrite so client-side routing works.

Then seed once against Atlas and create your administrator.

---

Troubleshooting

npm run dev fails on the database. If you left MONGODB_URI empty, the embedded MongoDB is downloading on first run and needs internet access. Behind a restrictive network that download can fail; install MongoDB locally or use Atlas and set MONGODB_URI instead. The error message says which.

"There are no published questions matching that selection." The filter is narrower than the bank. Widen it, or check Administration → Questions that the questions you expect are published.

A mock examination will not start. It needs enough published questions to fill each section. The error names the section and the shortfall. Publish more questions or reduce the section size in Administration → Mock Exams.

Signed out immediately after signing in. In production this is almost always CORS or cookies: CORS_ORIGINS must list your web address exactly, the API must be served over HTTPS, and VITE_API_URL must point at the API including /api.

Voice input does nothing. Speech recognition is unavailable in that browser. Type instead; the platform never requires it.

Theory marks look harsh. With no AI key the rubric engine is judging keyword and synonym coverage. Improve the rubric's synonyms for the criteria being missed, or configure AI marking.

The seed reports rows skipped. It prints the line number and the reason. The usual causes are a subject or topic title that does not match the syllabus exactly, or a published question with no explanation and no excerpt.

---

Honesty about the content

The platform distinguishes three kinds of content and labels every question with which it is:

• Official past paper — transcribed from a real examination paper.
• From the official syllabus — written from the syllabus, carrying the verbatim sentence that settles it.
• Demo content — illustrative only, never presented as official.

It also records how well each answer is supported: verified when the answer is traced to a syllabus passage, provisional when the passage supports it but a small inference is needed, and unverified when no supporting passage was found. Unverified questions are held at needs_review and do not reach candidates until a person confirms them, and the administrator dashboard surfaces the count.

Everything currently in the bank was written from the official 2026 syllabus and its excerpt was checked programmatically against the source text. Two caveats worth knowing: the source document carries some scanning damage, so a few excerpts reproduce an OCR artefact verbatim rather than silently correcting the syllabus; and where the syllabus states a list across several paragraphs, a single excerpt anchors the list rather than proving every item.

This is a study aid, not an authority. Check anything that matters against your printed syllabus before the examination.

---

Licence and attribution

The syllabus content reproduced here is the property of The Methodist Church Ghana, Lay Ministries Directorate, and is included for the personal study of candidates. It is not licensed for redistribution. The source documents are excluded from version control by .gitignore.

Scripture passages are bundled in the Authorised (King James) Version, which is free of copyright. ScriptureReference.translation records which version the stored text belongs to, so a differently licensed translation can be loaded in its place.