BooxRoom

BooxRoom is an AI-powered academic challenge arena where students take secure assessments, create practical projects, review every result, and turn weak topics into personalised paths to mastery.

Comment

Inspiration

As a teacher and software developer in Zambia, I have seen how disconnected the learning process can become.

Teachers spend many hours preparing examinations, lesson materials and academic records. Students then complete assessments and often receive only a final score. They may not clearly understand what they answered incorrectly, which topics require more attention or what they should study next.

I wanted to create a system where an assessment would not be the end of learning.

That idea became BooxRoom: an academic challenge and learner-improvement platform where teachers create secure assessment and practical challenges, students participate, results are reviewed in detail and weak topics automatically become personalised learning activities.

I also wanted BooxRoom to support more than traditional examinations. Learners should be able to demonstrate understanding by building models, designing solutions, conducting investigations, writing, performing, coding and creating projects.

The goal was to create a complete journey:

Challenge
→ Participation
→ Secure assessment
→ Meaningful feedback
→ Personalised improvement
→ Mastery

What it does

BooxRoom is an AI-assisted academic challenge platform for teachers, administrators and students.

It supports two main types of challenges.

Assessment challenges

Teachers can select an existing examination and convert it into a secure BooxRoom challenge.

The teacher can:

  • Add challenge instructions
  • Select public or private access
  • Preview exactly what students will see
  • Propose opening, closing and result-release times
  • Submit the challenge for administrative review

An administrator reviews the challenge, requests changes where necessary, approves it, publishes a protected student version and schedules the challenge.

Approved public challenges appear in the BooxRoom Academic Challenge Arena. Private challenges can be joined using a teacher-issued code.

During an assessment, BooxRoom provides:

  • Secure student authentication
  • Grade and eligibility checks
  • One attempt per student
  • Server-controlled timing
  • Stable random question order
  • Automatic answer saving
  • Refresh and resume support
  • Automatic submission when time expires
  • Protection of private answers and marking information

Objective questions are marked automatically. Written and subjective responses are sent to a moderation workspace where authorised reviewers can enter marks and finalise the result.

When results are released, students can see:

  • Their score and percentage
  • Competition points
  • Correct, incorrect and unanswered questions
  • Their submitted responses
  • Correct answers when review access is released
  • Topic and subtopic performance
  • Areas of strength
  • Areas that need more practice

Practical challenges

BooxRoom also allows teachers and administrators to create project-based challenges.

A teacher can select:

  • Grade
  • Subject
  • Topic
  • Subtopic
  • Practical challenge category

Categories include:

  • Build
  • Design
  • Create
  • Investigate
  • Perform
  • Code
  • Write
  • Research
  • Experiment
  • Present

AI can then generate a complete editable challenge containing:

  • Challenge title
  • Project description
  • Learning outcomes
  • Competencies
  • Learner instructions
  • Expected final product
  • Materials
  • Safety guidance
  • Milestones
  • Submission requirements
  • Reflection questions
  • Assessment rubric

For example, a learner studying cells can be asked to build and explain a three-dimensional model of a plant or animal cell.

Students receive a practical project workspace where they can submit:

  • Written explanations
  • Reflections
  • External links
  • Verified project images
  • An originality statement

Teachers and administrators review the submission using a rubric, provide feedback, request changes or release a final practical result.

Personalised improvement

BooxRoom does not stop after releasing a result.

It analyses performance by topic and classifies topics as:

  • Strong
  • Developing
  • Needs practice

Weak topics become a personalised improvement path containing:

  • Revision explanations
  • Worked examples
  • Common mistakes
  • Practice questions
  • Educational videos
  • BooxTutor support

These improvement activities never change the official assessment result or competition points.

How we built it

BooxRoom was built inside the existing BooxClash platform rather than as a separate application.

The main technology stack includes:

  • React 19
  • TypeScript
  • Vite
  • Tailwind CSS
  • Progressive Web App support
  • FastAPI
  • Python
  • Firebase Authentication
  • Cloud Firestore
  • Firebase Storage
  • Google Vertex AI
  • Gemini 2.5 Flash

The frontend communicates with FastAPI using Firebase identity tokens.

The backend follows a layered architecture:

Route
→ Pydantic validation
→ Domain service
→ Repository
→ Firestore or Firebase Storage

This structure helped separate HTTP handling, workflow rules, security validation and database operations.

Secure paper publishing

Assessment papers are split into two immutable versions:

Student-safe public paper
→ Questions, options, marks and safe explanations

Private marking paper
→ Correct answers, accepted variants and marking information

Both versions are published transactionally so students never receive private answer-key fields.

Attempt engine

The attempt engine was designed to survive real student behaviour and unreliable internet connections.

It includes:

  • Idempotent start and resume
  • Secure attempt ownership
  • Stable question randomisation
  • Monotonic answer revisions
  • Heartbeats
  • Browser recovery
  • Server-authoritative expiry
  • Retry-safe submission
  • Automatic grading checkpoints

Practical submission storage

Practical challenge images are uploaded using short-lived signed Firebase Storage URLs.

The backend generates storage paths such as:

booxroom/practical-submissions/{challengeId}/{studentUid}/{submissionId}/{fileId}

The system validates:

  • Student ownership
  • Challenge eligibility
  • Submission window
  • File count
  • MIME type
  • File extension
  • File size
  • Stored binary signature

Private storage paths are never returned to student-facing responses.

AI-assisted development

I used Codex powered by GPT-5.6 as an engineering partner while developing BooxRoom.

Codex helped me:

  • Inspect the existing React and FastAPI codebase
  • Understand incomplete workflows
  • Design secure multi-role state transitions
  • Implement challenge creation and approval
  • Strengthen the attempt engine
  • Build moderation and result-release workflows
  • Add practical challenge support
  • Improve structured error handling
  • Identify security and role-resolution problems
  • Write and run automated tests
  • Validate production builds

GPT-5.6 was used through Codex for software engineering. The current runtime generation and learning services use separately configured Vertex AI models.

Challenges we ran into

One of the biggest challenges was designing a secure end-to-end workflow rather than only creating attractive interfaces.

Role-resolution conflicts

At one point, the same authenticated teacher was correctly resolved as a teacher in one service but later replaced with a default student role in another helper.

This could have caused incorrect permissions.

We solved this by centralising actor resolution and ensuring that every protected route uses one authoritative identity and role.

Scheduling validation

Challenge scheduling required strict ordering between:

  • Opening time
  • Closing time
  • Result release
  • Answer-review release
  • Internal campaign boundaries

Early implementations produced conflicts when a hidden internal campaign ended before the complete challenge lifecycle.

We improved the scheduler so the backend validates every date and automatically creates suitable internal campaign boundaries.

Firebase Storage configuration

Practical challenge listing initially failed because the storage bucket was created eagerly whenever the service started, even for endpoints that did not need file uploads.

We changed Storage to use lazy initialisation so:

  • Challenge listing does not require Storage
  • Text and link submissions continue working
  • Storage is only accessed during file operations
  • Missing configuration produces a structured service error instead of an uncontrolled server crash

AI structured output

The AI practical generator initially failed because the generated response schema included unsupported validation keywords such as exclusiveMinimum.

We changed the generation process to use JSON response mode followed by strict Pydantic validation and rubric normalisation.

Protecting assessment information

It was essential to prevent correct answers, private marking instructions and internal identifiers from reaching students or public pages.

This required explicit student-safe and public allowlists instead of returning complete database objects.

Idempotency and recovery

Students may double-click, refresh, lose connectivity or retry requests.

We therefore had to design many actions to be idempotent, including:

  • Starting an attempt
  • Saving answers
  • Submitting
  • Grading
  • Publishing papers
  • Finalising moderation
  • Saving generated practical drafts

Accomplishments that we're proud of

I am proud that BooxRoom is now much more than a simple online examination interface.

It includes a connected workflow for:

Teacher creation
→ Administrative review
→ Secure publishing
→ Student participation
→ Automatic marking
→ Manual moderation
→ Result release
→ Question review
→ Topic analysis
→ Revision
→ Practice
→ BooxTutor

Other accomplishments include:

  • Building secure public and private challenge modes
  • Keeping answers and marking data separate from student papers
  • Supporting resumable timed assessments
  • Providing full question-by-question result review
  • Turning weak topics into personalised learning paths
  • Adding practical and competency-based challenges
  • Supporting verified image evidence
  • Adding rubric-based practical assessment
  • Creating AI-assisted challenge generation
  • Preserving official assessment results during remediation
  • Building the system inside an existing production-scale platform instead of starting a disconnected prototype

The BooxRoom backend reached more than 200 passing automated tests during development, and the frontend production and PWA builds were successfully validated.

What we learned

The most important lesson was that an education platform needs more than content generation.

A useful system must also handle:

  • Identity
  • Permissions
  • Workflow states
  • Ownership
  • Timing
  • Privacy
  • Moderation
  • Retry safety
  • Auditability
  • Result integrity
  • Follow-up learning

I also learned that AI is most valuable when it supports human decision-making rather than replacing it.

In BooxRoom:

  • Teachers review AI-generated practical challenges
  • Administrators approve challenges before publication
  • Reviewers control subjective marks
  • Students receive AI-supported explanations and revision
  • AI cannot alter official results

I learned to design public APIs using explicit safe projections, to separate private marking information from student content and to treat every repeated request as something that may happen in a real production environment.

Using Codex also showed me the value of an AI engineering partner that can reason across an existing codebase, inspect related services, identify incomplete flows and help validate changes through tests.

What's next for BooxRoom

The next phase is focused on production hardening and deeper learner creation.

Planned improvements include:

  • Supporting student onboarding for every grade available in practical challenges
  • Completing public practical challenge discovery and joining
  • Adding stronger practical review claims and immutable released results
  • Deploying and validating Firestore and Firebase Storage security rules
  • Adding recurring jobs for challenge release, expiry and reconciliation
  • Delivering notification outbox messages
  • Adding browser-based end-to-end testing
  • Completing physical mobile-device acceptance testing
  • Adding team practical challenges and shared submissions

  • Building creative student sandboxes for:

    • Drawing
    • Coding
    • Scratch projects
    • Game design
    • Music
    • Presentations
    • Digital portfolios

  • Creating challenge seasons, qualification pathways, rankings and recognition

  • Expanding curriculum support beyond Zambia

The long-term vision is for BooxRoom to become a global academic challenge and mastery platform where learners do not only answer questions.

They compete, create, understand, improve and rise.

Built With

Share this project:

Updates