# openedx/edx-when architecture

> Architecture diagram of the GitHub repository openedx/edx-when, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openedx/edx-when
- Repository: https://github.com/openedx/edx-when

## Overview

##### Main Components
- edx-when Application: At the core, this is a Django app that provides API endpoints, manages data models, and interacts with templates (for rendering views).
- Database: The app uses the same database as edx-platform, so the shared datastore is a central component.
- edx-platform Integration Points:
- Studio Interface: Where course publication triggers writing dates via signals.
- LMS: Where various components read the course scheduling information.
- External Dependencies: Include the shared configuration and possibly third-party Django libraries (highlighted in the requirements files) that support security, migrations, and API interactions.
- Supporting Infrastructure: Build system (Makefile, setup.py), CI workflows (GitHub workflows for testing, linting, publishing), and testing setups all support robust development and deployment.

##### Relationships and Interactions
- The edx-when Django app receives signals (from the course_date_signals handlers in Studio) to create or update course dates.
- When a course is published, Studio writes to the app (likely via a direct API call) which then stores the timing information in the shared database.
- The LMS reads these dates from the database in various locations to control course scheduling and display.
- Migration files in the “edx_when/migrations” directory indicate versioned changes to the DB schema over time. These add to the lifecycle management of data versioning.
- The app also exposes an admin interface (via admin.py) and an API (via api.py) to handle internal management and programmatic access respectively.

##### Architectural Patterns and Design Principles
- Modular Django App: The application follows Django’s standard practices with distinct directories for models, views, admin, migrations, and templates.
- Integration via Signals/Events: The architecture leverages Django signals or similar mechanisms to interface with course publishing events in Studio.
- Shared Data Model: Emphasis on a shared database across multiple parts of the edX platform, ensuring consistency of course-dates.

##### Relevant Technologies and Frameworks
- Python/Django (for the app, models, views, and migration system)
- GitHub Actions (CI workflows for linting, testing, and deployment)
- PyTest or Django’s Test Framework (as seen in the tests/ directories)
- Documentation build processes (Sphinx, Makefile under docs), ensuring clarity on API usage and architectural decisions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Studio (Course Publisher)"]:::external
    B["edx-when Django App Core"]:::app
    C["Shared Database"]:::db
    D["LMS (Course Consumer)"]:::external

    A -->|"publish_event"| B
    B -->|"store_dates"| C
    C -->|"read_dates"| D

    subgraph "Internal Modules"
        b1["Models"]:::app
        b2["Migrations"]:::app
        b3["API Endpoints"]:::app
        b4["Admin Interface"]:::app
        b5["Templates (Views)"]:::app
    end
    B --> b1
    B --> b2
    B --> b3
    B --> b4
    B --> b5

    subgraph "Supporting Infrastructure"
        G1["External Dependencies"]:::support
        G2["Build Config"]:::support
        E1["CI/CD (Workflows)"]:::support
        E2["CI/CD (Makefile)"]:::support
        F["Testing Infrastructure"]:::support
    end
    G1 --- B
    G2 --- B
    E1 --- B
    E2 --- B
    F --- B

    click B "https://github.com/openedx/edx-when/tree/master/edx_when/"
    click b1 "https://github.com/openedx/edx-when/blob/master/edx_when/models.py"
    click b2 "https://github.com/openedx/edx-when/tree/master/edx_when/migrations/"
    click b3 "https://github.com/openedx/edx-when/blob/master/edx_when/api.py"
    click b4 "https://github.com/openedx/edx-when/blob/master/edx_when/admin.py"
    click b5 "https://github.com/openedx/edx-when/tree/master/edx_when/templates/edx_schedule/"
    click G1 "https://github.com/openedx/edx-when/tree/master/requirements/"
    click G2 "https://github.com/openedx/edx-when/blob/master/setup.py"
    click E1 "https://github.com/openedx/edx-when/tree/master/.github/workflows/"
    click E2 "https://github.com/openedx/edx-when/tree/master/Makefile"
    click F "https://github.com/openedx/edx-when/tree/master/tests/"

    classDef app fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef db fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef support fill:#FFFF99,stroke:#000,stroke-width:2px;
```
