feat: new catalog app to model course runs and catalog courses

Author: bradenmacdonald

projects/dev.py

@@ -34,6 +34,9 @@
     "django.contrib.admin",
     "django.contrib.admindocs",
 
+    # Open edX Organizations (dependency for openedx_catalog)
+    "organizations",
+
     # Our Apps
     "openedx_tagging",
     "openedx_content",

src/openedx_catalog/ARCHITECTURE.md

@@ -0,0 +1,35 @@
+# Catalog App Architecture Diagram
+
+Here's a visual overview of how this app relates to other apps.
+
+(_Note: to see the diagram below, view this on GitHub or view in VS Code with [a Markdown-Mermaid extension](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) enabled._)
+
+```mermaid
+---
+config:
+  theme: 'forest'
+---
+flowchart TB
+    Catalog["**openedx_catalog** (CourseRun, CatalogCourse plus core metadata models, e.g. CourseSchedule. Other metadata models live in other apps but are 1:1 with CourseRun.)"]
+    Content["**openedx_content**<br>The content of the course. (publishing, containers, components, media)"]
+    Organizations["**edx-organizations** (Organization)"]
+    Enrollments["**platform: enrollments** (CourseEnrollment, CourseEnrollmentAllowed)"]
+    Modes["**platform: course_modes** (CourseMode)"]
+    Catalog <-. "Direction of this relationship TBD." .-> Content
+    Catalog -- References --> Organizations
+    Enrollments -- References --> Modes
+    Enrollments -- References --> Catalog
+
+    style Enrollments fill:#ccc
+    style Modes fill:#ccc
+    style Organizations fill:#ccc
+
+    Pathways["<a href='https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5148147732/Brief+Modular+Content+Delivery+-+Platform+Strategy'>**openedx_pathways**</a> (Pathway, PathwaySchedule, PathwayEnrollment, PathwayCertificate, etc.)"]
+    Pathways -- References --> Catalog
+
+    style Pathways fill:#c0ffee,stroke-dasharray: 5 5
+
+    FutureCatalog["Future discovery service - learner-oriented, pluggable, browse/search courses and programs"] -- References --> Catalog
+    FutureCatalog <-- Plugin API --> Pathways
+    style FutureCatalog fill:#ffc0ee,stroke-dasharray: 5 5
+```

src/openedx_catalog/README.rst

@@ -0,0 +1,22 @@
+Learning Core: Catalog App
+==========================
+
+Overview
+--------
+
+The ``openedx_catalog`` Django apps provides core models to represent all courses in the Open edX platform. Higher-level apps can build on these models to implement features like enrollment, grading, scheduling, exams, and much more.
+
+Motivation
+----------
+
+The existing ``CourseOverview`` model in ``openedx-platform`` is derived from various places, but mostly from the metadata fields of the root ``Course`` object stored in modulestore (MongoDB) for each course. As we slowly transition toward storing course content fully in Learning Core (in ``openedx_content``), we want to move to storing all course data and metadata in these sort of MySQL models. We're creating this new ``CourseRun`` model in ``openedx_catalog`` to support these goals:
+
+1. Provide a core model to represent each course, for foreign key purposes.
+2. To allow provisioning placeholder courses before any content even exists.
+3. To be much simpler and more performant than ``CourseOverview`` was (far fewer fields generally, fewer legacy fields, integer primary key).
+4. Perhaps to provide a transition mechanism, a pointer than can point either to modulestore content or learning core content, as we transition content storage.
+
+Architecture
+------------
+
+See `the architecture diagram <./ARCHITECTURE.md>`__. (Because we use RST for all Python READMEs, it cannot be embedded here directly.)

src/openedx_catalog/__init__.py

@@ -0,0 +1,64 @@
+"""
+Django Admin pages for openedx_catalog.
+"""
+
+from django.contrib import admin
+from django.db.models import Count
+from django.urls import reverse
+from django.utils.html import format_html
+from django.utils.translation import gettext_lazy as _
+
+from .models import CatalogCourse, CourseRun
+
+
+class CatalogCourseAdmin(admin.ModelAdmin):
+    """
+    The CatalogCourse model admin.
+    """
+
+    list_filter = ["org_id", "language"]
+    list_display = ["display_name", "org", "course_code", "runs_summary", "language"]
+
+    def get_readonly_fields(self, request, obj: CatalogCourse | None = None):
+        if obj:  # editing an existing object
+            return self.readonly_fields + ("org", "course_code")
+        return self.readonly_fields
+
+    def get_queryset(self, request):
+        """Add the 'run_count' to the list_display queryset"""
+        qs = super().get_queryset(request)
+        qs = qs.annotate(run_count=Count("runs"))
+        return qs
+
+    def runs_summary(self, obj: CatalogCourse) -> str:
+        """Summarize the runs"""
+        if obj.run_count == 0:
+            return "-"
+        url = reverse("admin:openedx_catalog_courserun_changelist") + f"?catalog_course={obj.pk}"
+        first_few_runs = obj.runs.order_by("-run")[:3]
+        runs_summary = ", ".join(run.run for run in first_few_runs)
+        if obj.run_count > 4:
+            runs_summary += f", ... ({obj.runs_count})"
+        return format_html('<a href="{}">{}</a>', url, runs_summary)
+
+
+admin.site.register(CatalogCourse, CatalogCourseAdmin)
+
+
+class CourseRunAdmin(admin.ModelAdmin):
+    """
+    The CourseRun model admin.
+    """
+
+    list_display = ["display_name", "catalog_course", "run", "org_id"]
+    readonly_fields = ("course_id",)
+    # There may be thousands of catalog courses, so don't use <select>
+    raw_id_fields = ["catalog_course"]
+
+    def get_readonly_fields(self, request, obj: CourseRun | None = None):
+        if obj:  # editing an existing object
+            return self.readonly_fields + ("run",)
+        return self.readonly_fields
+
+
+admin.site.register(CourseRun, CourseRunAdmin)

src/openedx_catalog/admin.py

@@ -0,0 +1,19 @@
+"""
+App Config for the openedx_catalog app.
+"""
+
+from django.apps import AppConfig
+
+
+class CatalogAppConfig(AppConfig):
+    """
+    Initialize and configure the Catalog app
+    """
+
+    name = "openedx_catalog"
+    verbose_name = "Open edX Core > Catalog"
+    default_auto_field = "django.db.models.BigAutoField"
+    label = "openedx_catalog"
+
+    def ready(self) -> None:
+        pass

src/openedx_catalog/apps.py

@@ -0,0 +1,165 @@
+# Generated by Django 5.2.11 on 2026-02-10 03:08
+
+import django.db.models.deletion
+import opaque_keys.edx.django.models
+import openedx_catalog.models.catalog_course
+import openedx_django_lib.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = [
+        ("organizations", "0004_auto_20230727_2054"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="CatalogCourse",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        editable=False,
+                        help_text="The internal database ID for this catalog course. Should not be exposed to users nor in APIs.",
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="Primary Key",
+                    ),
+                ),
+                (
+                    "course_code",
+                    openedx_django_lib.fields.MultiCollationCharField(
+                        db_collations={"mysql": "utf8mb4_bin", "sqlite": "BINARY"},
+                        help_text='The course ID, e.g. "Math100".',
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "display_name",
+                    models.CharField(
+                        help_text='The full name of this catalog course. e.g. "Introduction to Calculus". Individual course runs may override this, e.g. "Into to Calc (Fall 2026 with Dr. Newton)".',
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "language",
+                    models.CharField(
+                        default=openedx_catalog.models.catalog_course.get_default_language_code,
+                        help_text='The code representing the language of this catalog course\'s content. The first two digits must be the lowercase ISO 639-1 language code. e.g. "en", "es", "en-us", "pt-br". ',
+                        max_length=64,
+                    ),
+                ),
+                (
+                    "org",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        to="organizations.organization",
+                        to_field="short_name",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Catalog Course",
+                "verbose_name_plural": "Catalog Courses",
+            },
+        ),
+        migrations.CreateModel(
+            name="CourseRun",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        editable=False,
+                        help_text="The internal database ID for this course. Should not be exposed to users nor in APIs.",
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="Primary Key",
+                    ),
+                ),
+                (
+                    "course_id",
+                    opaque_keys.edx.django.models.CourseKeyField(
+                        editable=False,
+                        help_text="The main identifier for this course. Includes the org, course code, and run.",
+                        max_length=255,
+                        unique=True,
+                        verbose_name="Course ID",
+                    ),
+                ),
+                (
+                    "run",
+                    openedx_django_lib.fields.MultiCollationCharField(
+                        db_collations={"mysql": "utf8mb4_bin", "sqlite": "BINARY"},
+                        help_text='The code that identifies this particular run of the course, e.g. "2026", "2026Fall" or "2T2026"',
+                        max_length=128,
+                    ),
+                ),
+                (
+                    "display_name",
+                    models.CharField(
+                        blank=True,
+                        help_text='The full name of this course. e.g. "Introduction to Calculus". This is required and will override the name of the catalog course. Leave blank to use the same name as the catalog course. ',
+                        max_length=255,
+                    ),
+                ),
+                (
+                    "catalog_course",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="runs",
+                        to="openedx_catalog.catalogcourse",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Course Run",
+                "verbose_name_plural": "Course Runs",
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="catalogcourse",
+            constraint=models.UniqueConstraint(
+                fields=("org", "course_code"), name="oex_catalog_catalog_course_org_code_pair_uniq"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="catalogcourse",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("course_code__length__gt", 0)),
+                name="oex_catalog_catalogcourse_course_code_not_blank",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="catalogcourse",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("language__length__gt", 0)), name="oex_catalog_catalogcourse_language_not_blank"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="catalogcourse",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("display_name__length__gt", 0)),
+                name="oex_catalog_catalogcourse_display_name_not_blank",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="courserun",
+            constraint=models.UniqueConstraint(
+                fields=("catalog_course", "run"), name="oex_catalog_courserun_catalog_course_run_uniq"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="courserun",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("run__length__gt", 0)), name="oex_catalog_courserun_run_not_blank"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="courserun",
+            constraint=models.CheckConstraint(
+                condition=models.Q(("display_name__length__gt", 0)), name="oex_catalog_courserun_display_name_not_blank"
+            ),
+        ),
+    ]

src/openedx_catalog/migrations/0001_initial.py

@@ -0,0 +1,6 @@
+"""
+Models that commprise openedx_catalog
+"""
+
+from .catalog_course import CatalogCourse
+from .course_run import CourseRun