ADR: API Endpoint for User Exam Due Dates in the Mobile App

[SergiiKalinchuk]

Context

To improve the Open edX mobile experience, we need to provide learners with a fast, accurate list of upcoming exam and assignment due dates across all of their enrolled courses. This is critical for enabling mobile-first learning workflows, proactive planning, and push notifications.

The current approach, which relies on get_course_date_blocks() and modulestore traversal, is inefficient, especially for multi-course scenarios. The Open edX community has committed to limiting modulestore usage in runtime systems (ADR 0011) and modularizing content and date management.

Solution Summary

We are going to reuse and extend the edx-when application as the unified backend for both course-level and user-level due dates:

• Use ContentDate to store published due dates from course metadata
• Use UserDate to store user-specific overrides, including:
  • Personalized schedules (self-paced)
  • Instructor-granted extensions
• Create a new API endpoint to return a merged and filtered list of upcoming due dates for the authenticated user

Rejected Alternatives

The following approaches were considered during the design phase but ultimately rejected due to technical or architectural limitations:

1. Continue Using Only XBlock Metadata for Dates

• Description: Store all start, due, and graceperiod fields in the modulestore within XBlock definitions.
• Reason for Rejection:
  • No support for user-level overrides.
  • Requires course republishing for any change.
  • Cannot support dynamic scheduling, self-paced courses, or extensions.

2. Use Only the schedules App to Drive Dates

• Description: Centralize all date logic through schedules.Schedule and schedules.CourseDateOverride.
• Reason for Rejection:
  • Not designed for block-level (e.g., exam-specific) due dates.
  • Cannot serve instructor-paced or hybrid course modes.
  • Adds significant refactor requirements to upstream LMS and Mobile APIs.

3. Store Dates in a Separate Custom Table or External Service

• Description: Introduce a new app or microservice for handling exam due dates independently of edx-when.
• Reason for Rejection:
  • Duplicates functionality already available in edx-when.
  • Adds operational and architectural overhead.
  • Increases latency and coupling across services.

4. Compute Dates On-the-Fly at Runtime

• Description: Dynamically calculate due/start dates based on enrollment and pacing without persisting them.
• Reason for Rejection:
  • Degrades performance at scale.
  • No audit trail or persistence for extension history.
  • Makes date behavior inconsistent and hard to debug.

The final decision to use and extend the edx-when data model preserves flexibility, supports both default and override scenarios, and ensures consistent integration across all platform interfaces (LMS, MFE, Mobile).

Impact on Existing Functionality

Based on our review of the current Open edX codebase, the ContentDate and UserDate models from the edx-when module are not widely integrated into core platform components at this time. Their usage appears to be limited, with no direct dependencies from LMS rendering paths or block structure transformers in the default configuration of the platform.

As a result, the changes proposed in this ADR are not expected to impact existing functionality. The models in question do not currently serve as a critical path for date resolution in standard learner-facing APIs or courseware behavior.

Architecture Overview

✅ What We Reuse

Component	Role
edx-when.ContentDate	Stores canonical due dates published for each course content element
edx-when.UserDate	Stores per-user overrides (e.g., extensions, personalized pacing)
Schedules	Provides start_date for self-paced learners (used in overrides)

🆕 What We Add

Component	Purpose
New API	Returns all due dates visible to the user across their courses
Runtime logic	Merges ContentDate and UserDate, applies filtering/visibility

---

Data Flow

1. Studio authors define dates → written to ContentDate via publishing
2. Overrides from instructors or learners → stored in UserDate
3. Mobile client calls new API /api/user-due-dates/
4. Backend logic:
   • Loads enrolled courses
   • Retrieves corresponding ContentDate and UserDate records
   • Applies overrides and visibility checks
   • Returns sorted, paginated results

API Responsibilities

The new API will:

• Authenticate the user
• Retrieve the list of enrolled courses
• Fetch all related ContentDate and UserDate entries
• Apply overrides and enforce content visibility
• Return fields such as:
  • course_id
  • title
  • due_date
  • first_component_block_id
  • override_source (if applicable)

Scope Limitations

❌ CCX courses (Custom Courses for EdX) are excluded from this implementation due to their unique override structure and management.

Benefits

• ✅ Performance: Indexed queries instead of runtime block traversal
• ✅ Consistency: All dates managed in one canonical system
• ✅ Maintainability: No need to create redundant data models
• ✅ Scalability: Reusable for LMS, mobile, and analytics
• ✅ Forward-compatible: Aligned with plans to remove MongoDB and improve RBAC

Next Steps

1. Ensure publishing pipeline writes dates to ContentDate
2. Use UserDate to record instructor and learner overrides
3. Build new endpoint /api/user-due-dates/
4. Merge base and override dates at runtime
5. Implement access control and visibility filtering
6. Monitor for latency, accuracy, and correctness

[SergiiKalinchuk]

[NiedielnitsevIvan]

@SergiiKalinchuk Thank you for the research and hard work!
Can you please add more details on where the CourseDate and UserDate models are currently used, and whether what is described in this ADR will break the existing functionality?
And also in case of plans to extend these models, I think it's worth mentioning it here in more detail.
I think it's worth adding Rejected Alternatives here, describing the solutions that were discussed and what problems we encountered that made us abandon these approaches.

[SergiiKalinchuk]

@NiedielnitsevIvan Good points, thank you for suggestions! I updated the ticket, mentioning current limited usage of ContentDate and UserDate models from edx-when module, as well as adding Rejected Alternatives section.

[kdmccormick]

As a whole, this sounds like a good plan. Some questions:

• Where will the new REST API be defined?
• It sounds like the API will include business logic to compose base and override dates. Can this logic be implemented in a Python API, which the REST API would thinly wrap? This would allow the Python API to be reused in other parts of the platform in the future.
• What are DateTransformers?

[SergiiKalinchuk]

@kdmccormick Thank you for the feedback. Here are my thoughts on it:

1. Where will the new REST API be defined?

The new REST API will be implemented in the edx-when Django app itself, under a dedicated v1 endpoint namespace such as: /api/edx_when/v1/user-dates/

This location was chosen to colocate the API with the underlying models (ContentDate, UserDate) and related business logic, ensuring encapsulation and modular reuse. If broader consensus emerges that these endpoints should instead reside in a more central application (e.g., courseware or lms), we’re open to relocation during the review phase.

2. Will the API logic be reusable in a Python API?

Yes, of course, we are looking for reusability. The REST API will be a thin wrapper around a dedicated Python service layer. This service layer will:

• Accept a user_id, course_id, and optional filtering parameters (e.g., XBlock keys or date types).
• Internally resolve dates by composing: defaults from ContentDate, and overrides from UserDate (if applicable).
• Return a consistent structure for integration in LMS views, mobile endpoints, or task pipelines.

This design allows:

• LMS rendering code to call the Python API directly (avoiding HTTP overhead).
• Mobile apps to use the REST API.
• Background jobs (e.g., for scheduling or notifications) to share the same logic.

We will document and test the Python API as a first-class interface to encourage platform-wide reuse.

3. What are DateTransformers?

Indeed, there is no formal class or utility named DateTransformer in the current Open edX codebase.

That term appeared in some earlier architectural explorations, and it was an informal reference to the transformer pattern used in the block_structure system (e.g., StartDateTransformer, BlockCompletionTransformer, etc.), where transformers mutate the structure or metadata of course blocks at render time.

In the context of edx-when, the idea was that a similar transformer could eventually resolve and attach user-specific dates onto XBlocks during course rendering.

That said, since this concept is not part of the actual implementation plan and may introduce confusion, we’ll remove or rename references to DateTransformers in the ADR for clarity. The new API layer will serve a similar purpose but more explicitly and in a centralized fashion.

[kdmccormick]

The new REST API will be implemented in the edx-when Django app itself

If this is feasible, great. It is nice to have APIs encapsulated into their related package when it's possible to do so.

However, we must be sure that edx-when is not importing code from edx-platform. That breaks the encapsulation and removes much of the benefit of separating edx-when into its own self-contained package. For example, this import in edx-when is an anti-pattern which we should not replicate.

If it is possible to implement the REST API in edx-when without importing edx-platform, great 👍🏻 If not, then I would prefer that the REST API live within edx-platform.

We will document and test the Python API as a first-class interface to encourage platform-wide reuse.

Great!

That said, since this concept is not part of the actual implementation plan and may introduce confusion, we’ll remove or rename references to DateTransformers in the ADR for clarity.

Yes, please remove or clarify. Thanks!

[kdmccormick]

The flowchart still references DateTransformers, could you update that as well @SergiiKalinchuk ?

[SergiiKalinchuk]

@kdmccormick Renamed to a more general term "API Layer"

[kdmccormick]

Is this the edx-when API Layer ? "uses edx-when" tells me that it is an API layer in edx-platform.

[SergiiKalinchuk]

Is this the edx-when API Layer ? "uses edx-when" tells me that it is an API layer in edx-platform.

@kdmccormick Sorry for mislabelling, I actually referred to a service layer, which will reside in edx-when and will resolve dates for the APIs. Fixed the image accordingly

[kdmccormick]

Thanks for the edit. With that understanding, I'd like to review this one more time.

[awais786]

@kdmccormick are you still looking to work on this ?