A Shuffled Procurement Exam Quiz So You Can't Just Memorize the Order
A FastAPI practice site for the Government Procurement Act exam: how it parses the official PDF question bank, shuffles every quiz, and tracks weak categories.
I built this project because my wife signed up for the Government Procurement Act certification exam.
If you practice straight from the PDF question bank a few times, it’s easy to end up memorizing the question order along with the answers. Before you turn the page, the answer has already popped into your head. That familiarity can’t tell you whether you remember the material or just where the answer sits in the PDF.
So I set out to turn a fixed question bank into practice rounds that come in a different order every time and still leave a record of your weak areas.
Once the question order is shuffled, familiarity can no longer stand in for understanding.
This post examines commit
b29fe3f.pyproject.tomldeclares package version0.1.0and requires Python3.11or later.
A web app that turns the official question bank into practice records
gpa-question-webapp is a practice site for the Government Procurement Act question bank. It uses FastAPI, SQLAlchemy, Jinja2, pdfplumber, and python-docx, and is released under the MIT License.
It has two data paths. On import, parse_command reads the official PDF or DOCX files you’ve downloaded locally and writes the questions into PostgreSQL. During practice, the browser UI calls FastAPI to read and write questions, sessions, and answer records.
Architecture diagram based on commit b29fe3f; open the interactive version.
The browser-facing routes are wired up in src/api/main.py and cover four features:
- Randomized practice
- Instant answer checking
- Per-session scores
- Cross-session weak-area stats
How data travels from a PDF to an answerable question
The first stage is import. The CLI scans the input directory for .pdf and .docx files and hands each one to the parser that matches its extension. If no category is specified, a leading 1 to 13 in the filename is treated as the category number. See src/ingestion/cli.py.
The PDF parser first splits the document at the Chinese headings for “true/false questions” (是非題) and “multiple-choice questions” (選擇題). It then uses regular expressions to recognize question numbers and answers. Multiple-choice answers 1 to 4 become A to D. The rules are in src/ingestion/pdf_parser.py:
1
2
3
MC_QUESTION_START = re.compile(r"^\s*(\d+)\s+([1-4])\s+(.+)")
TF_QUESTION_START = re.compile(r"^\s*(\d+)\s+([OX])\s+(.+)")
ANSWER_NUM_TO_LETTER = {"1": "A", "2": "B", "3": "C", "4": "D"}
The second stage is deduplication and updating. Each question’s source_hash is the SHA-256 of its category, question type, and question text joined together:
1
2
3
4
@property
def source_hash(self) -> str:
raw = f"{self.category_id}|{self.question_type}|{self.question_text}"
return hashlib.sha256(raw.encode("utf-8")).hexdigest()
On re-import, a question with a matching hash gets its answer, options, or legal reference updated. Questions that have disappeared from the source get marked with deleted_at. The full flow is in src/ingestion/base.py.
Practice only begins in the third stage. Questions reach the browser without the correct answer, and the server checks each answer:
sequenceDiagram
participant B as Browser
participant API as FastAPI
participant DB as PostgreSQL
B->>API: Start practice with categories, types, count
API->>DB: Shuffle with func.random, take N
API-->>B: Questions, no answers
B->>API: Submit answer
API->>DB: Check and record result
API-->>B: Return correct answer
create_session draws the questions, shuffling the matching ones with func.random(). The QuestionResponse you get first has no correct-answer field. Checking happens in submit_answer.
Weak areas aren’t guessed; they accumulate by category
I think the part most worth checking here is what “cross-session weak areas” actually computes.
“Cross-session weak areas” means the cumulative accuracy of each category, with a clear denominator, threshold, and sort order:
flowchart TD
A[Find records by anonymous_id] --> B[Group answers by category]
B --> C["Accuracy = correct ÷ answered"]
C --> D[Sort lowest first]
D --> E[Frontend keeps under 80%]
E --> F[Take up to five]
F --> G["'Practice weak areas' button"]
On the backend, get_weakness stops after sorting. The 80% threshold and the five-category cap live in the frontend, in src/templates/weakness.html:
1
2
const weakCats = data.categories.filter(c => c.percentage < 80).slice(0, 5);
const weakIds = weakCats.map(c => c.category_id).join(',');
It isn’t an ability-estimation model, and it doesn’t give extra weight to recent results. If you answer the same question several times, every attempt counts toward the stats. I worked out these limits from how the code counts SessionAnswer.id rows, not from the README’s description of the feature.
The price of convenience: format coupling and anonymous identity
The parser depends directly on the layout text and answer format of the official documents. If the section headings no longer read “true/false questions” or “multiple-choice questions,” or multiple-choice answers no longer use 1 to 4, the current rules stop recognizing questions. You can see this maintenance cost in _split_sections and the two question-type parsing functions.
The runtime isn’t a single static web page, either. docker-compose.yml starts the application and PostgreSQL 16, and keeps data in a pgdata volume. If practice records need to survive a disk failure, you have to arrange backups separately when you deploy.
Cross-session identity relies only on gpa_anonymous_id in the browser’s localStorage. The frontend puts it into the /api/weakness query string, as shown in src/templates/weakness.html. The matching route only accepts anonymous_id and has no account-authentication dependency.
I find that convenient for a household tool, but it isn’t the access control you’d want for storing official exam scores.
Good for home practice, not a ready-made official exam system
If your question bank comes from a fixed source, your users are a known group, and you only need shuffled questions plus the categories you keep missing, this project already wires the necessary pieces together. When the question bank changes, upsert_questions can update, keep, or soft-delete existing questions, so you don’t have to wipe the database each time.
To open it up to many users, you first need accounts, authorization, data isolation, and a backup strategy. If the question bank’s layout changes often, the parser also needs failure reports and tests for new formats. As I see it, the current code suits a personal practice tool and shouldn’t be treated as an official exam platform as-is.
Run the tests first, then plug in your own question bank
Confirm the dependencies, the CLI entry point, and the core behavior before you deal with the official question-bank files. I ran the commands below on macOS with Python 3.14.2 and uv 0.9.17:
1
2
3
4
5
git clone https://github.com/7a6ac0/gpa-question-webapp.git
cd gpa-question-webapp
uv sync --extra dev
uv run python -m src.ingestion.cli --help
uv run pytest -q
I got 34 passed in 1.05s, and the CLI listed the parse subcommand. This only confirms that the current commit installs and passes its tests. It doesn’t mean every version of the official PDF will parse.
Next, download one category’s file from the Public Construction Commission question bank page and put it in data/. Then process it with the import command in the project README and check the parsing results.
What really matters is a practice record you can look back on
Everything checked above confirms only that these features exist. It can’t prove the project will raise exam scores. I still judge that its value lies in closing a review loop.
A fixed PDF gives you only questions and answers, while the website turns every attempt into data. Randomized quizzes cut off the question-order cues, and category stats point to what to practice next round. For my family’s need, the tech choices are just a means. The real product is being able to keep repeating “answer, find weak areas, practice again.”
Further reading
- gpa-question-webapp source code: the import, answering, and weak-area stats code discussed here.
- Public Construction Commission procurement professional question bank: the official source this project processes.
- FastAPI documentation: routing, response models, and dependency injection.
- SQLAlchemy 2.0 documentation: sessions, queries, and ORM relationships.
