Backend (Flask) — Findability, Assembly, Conversion, Difficulty, History, Guardrails, Solutions

What this adds

• JWT auth (/auth/login, /auth/whoami) + @require_role guard.
• Findability: GET /questions with q (LIKE), qs (FTS ranked), course, q_type, ext, difficulty, tags, used_after, used_before, paging.
• Fast indexes: GIN FTS + common BTrees (created idempotently on start).
• Solutions: POST /questions/<qid>/solutions.
• Assembly:
  • POST /assemblies/auto_build (balanced diff mix; prefers not-recently-used).
  • GET /assemblies/<id>/export?fmt=md|qti (includes times_used/last_used, writes usage_log + bumps counters).
• Conversion: minimal IMS QTI v2.1 XML export.
• Adaptive difficulty:
  • POST /metrics/ingest
  • POST /metrics/recompute_difficulty (weighted avg → easy/medium/hard; stores in calibrated_difficulty and updates questions.difficulty).
• History: question_revisions (scaffold) + usage_log.

Getting Started

System Requirements

• Python 3.9+
• PostgreSQL 16+
• Streamlit 1.38+
• Git, Docker
• Node.js 18+ (for optional frontend features)

1. Clone the Repository

Run the following commands in your terminal:

git clone https://github.com/tengquanhan687/dsa3101-2510-quiz-bank-4.git
cd dsa3101-2510-quiz-bank-4

2. Build and Run the Docker containers

In the terminal, run the following command at the root of the repository:

docker compose up

This will begin the construction of the database, backend and frontend containers.

Note: During the building process of the containers, you will see messages like:

INFO:__main__:Waiting for DB to be available…
INFO:backend.app:Waiting for DB to be available…

This does not affect the functionalities of the containers; allow the containers some time to build.

3. Access the App

Once you see:

INFO:werkzeug:Press CTRL+C to quit

it means the containers are done building. You can then access the application at:

http://localhost:8501