Implement MongoDB-backed worksheet generation locking

[Chirashrikarmakar]

Summary

Implemented MongoDB-backed permanent worksheet generation locking for the FLN Assessment Platform.

The feature prevents duplicate question paper generation for the same assessment and school. When a teacher generates a question paper, a permanent lock is created and stored in MongoDB. Any further generation attempts for the same assessment and school are rejected.

The backend locking mechanism is fully implemented using MongoDB. However, the current application flow still uses the frontend mock backend (fetchInterceptor.ts) for many API routes. Because of this, the UI generation flow may not always reach the real Express backend and MongoDB layer during testing.

Implementation Details

MongoDB Lock Persistence

• Added a new GenerationLock MongoDB model to store worksheet generation locks.
• Added MongoDB connection handling for persistent lock storage.
• Integrated MongoDB-based locking into the worksheet generation flow.
• Locks remain stored permanently in MongoDB after successful generation and survive backend restarts.

Permanent Generation Locking Flow

The implemented workflow:

Teacher clicks "Generate Question Paper"
↓
Request reaches backend
↓
Backend creates a MongoDB generation lock
↓
Question paper generation starts
↓
Lock remains permanently after successful generation

If the teacher tries to generate the same question paper again:

Generate Request
↓
Backend checks MongoDB lock
↓
Existing lock found
↓
Request rejected with HTTP 423 Locked

This ensures that only one question paper can be generated for the same assessment and school.

Concurrency Protection

• Implemented atomic lock creation using GenerationLock.create().
• Added MongoDB unique constraint using:
  • assessmentId
  • schoolId
• Prevented multiple simultaneous generation requests from creating duplicate question papers.
• Added handling for MongoDB duplicate key error (11000).
• Returns HTTP 423 Locked when a generation lock already exists.

Lock Lifecycle Management

• Lock is created when the teacher starts question paper generation.
• Lock remains permanently after successful generation.
• Lock cleanup is performed only when generation fails.
• Prevents invalid permanent locks while maintaining duplicate generation protection.

Lock Identification

Locks are uniquely identified using:

assessmentId + schoolId

This guarantees:

• One question paper generation per assessment and school.
• Duplicate question paper generation is prevented.
• Concurrent generation requests are handled safely.
• Lock data remains persistent through MongoDB.

Verification

Verified the backend implementation:

• MongoDB connection is established successfully.
• GenerationLock model is integrated with the worksheet generation flow.
• Lock creation logic works when the real backend endpoint is called.
• Duplicate generation protection works through MongoDB unique constraints.
• Duplicate lock attempts return HTTP 423 Locked.

Current Limitation

The project currently uses an in-browser mock backend for many API routes.

Current flow:

React Frontend
↓
fetchInterceptor.ts
↓
localStorage Mock Database

instead of:

React Frontend
↓
Express Backend
↓
MongoDB

Because of this existing architecture:

• The frontend generation flow may not always call the real backend generation API.
• MongoDB generationlocks collection may remain empty when the mock API handles the request.
• Complete end-to-end verification requires routing worksheet generation requests through the real backend API instead of the mock interceptor.

The MongoDB locking implementation itself is complete and ready for integration with the real backend workflow.

Files Changed

• backend/src/models/GenerationLock.ts

  • Added MongoDB schema and model for generation locks.

• backend/src/mongodb.ts

  • Added MongoDB connection support.

• backend/src/index.ts

  • Integrated MongoDB lock creation and duplicate generation prevention.

• backend/package.json

  • Added required MongoDB/Mongoose dependency.