# edx/learning-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/edx/learning-assistant
- Repository: https://github.com/edx/learning-assistant

## Overview

##### Project type and purpose
- This is a Django “plugin” app named learning_assistant that integrates into the Open edX LMS (and related services) to provide a chat-based learning assistant backend.
- It exposes REST/JSON endpoints consumed by a separate React frontend library (`frontend-lib-learning-assistant`) and orchestrates calls to an external Chat Completion API.

##### File structure
- Top-level: configuration (Makefile, setup.py, requirements/, .github/CI, docs/), Django management entry (`manage.py`), test suite (`tests/`).
- The `learning_assistant/` folder is a standard Django app:
- `models.py` (ORM definitions)
- `serializers.py` and `api.py`/`views.py` (DRF serializers & view logic)
- `urls.py` (URL routing)
- `plugins_api.py` (Open edX plugin interface)
- `toggles.py` (waffle flags)
- `management/commands/` (custom Django commands)
- `conf/locale/` (i18n)
- Migration files under `learning_assistant/migrations/` track database schema.
- Test files parallel the logic to ensure coverage.

##### Key insights from README
- The app depends on:
- edx-platform (LMS + Discovery + Ecommerce)
- External chat service (configured by `CHAT_COMPLETION_API` & API key)
- Frontend static package (`frontend-lib-learning-assistant`)
- Waffle feature flags for activation.

##### Components
a. Main Components
- User’s Browser & React frontend (`frontend-lib-learning-assistant`)
- edX LMS Platform (Django host)
- Django Core & edx-platform services (LMS, Discovery, Ecommerce)
- learning_assistant Django app
· API layer (`api.py`/`views.py`)
· Serializers & Plugins API
· Business logic (`utils.py`, `text_utils.py`, `data.py`)
· Database (PostgreSQL via Django ORM)
· Feature toggles (`toggles.py`)
· Management commands (e.g., retire old messages)
- External Chat Completion Service (e.g., OpenAI-like endpoint)
b. Relationships & Interactions
1. Browser loads course page + injects React widget from `frontend-lib-learning-assistant`.
2. Widget sends AJAX calls to LMS at `/learning-assistant/api/...`.
3. Django REST views authenticate/authorize (respect waffle toggles).
4. Incoming messages get serialized and saved to DB (models).
5. Business logic packages a prompt and issues HTTP request to external CHAT_COMPLETION_API.
6. Response received, persisted (audit trail), returned as JSON to frontend.
7. User sees response in chat UI.
8. Periodic cleanup via management command (`retire_user_messages`).
c. Architectural Patterns & Design Principles
- Modular Django app following MVC (models, views, templates are replaced by serializers+API).
- DRF for API design.
- Open edX plugin interface for service discovery/registration.
- Waffle flags for feature gating.
- Strict separation: “frontend” (React widget) vs. “backend” (Django app) vs. external AI service.
d. Key Technologies & Frameworks
- Python 3 + Django
- Django REST Framework
- edX plugin framework
- PostgreSQL (via Django ORM)
- Waffle (feature flags)
- External Chat Completion API
- pytest, tox for CI/testing
- Docker/devstack for local environment

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Frontend Layer"
    Browser["User Browser + React Widget"]:::frontend
  end

  subgraph "edX LMS (Django)"
    direction TB
    subgraph "Learning Assistant App"
      direction TB
      Apps["App Config (apps.py)"]:::backend
      URLRouting["URL Routing (urls.py)"]:::backend
      APIpy["API Layer api.py"]:::backend
      Views["API Layer views.py"]:::backend
      Serializers["Serializers (serializers.py)"]:::backend
      Models["ORM Models (models.py)"]:::backend
      PluginsAPI["Open edX Plugin Interface (plugins_api.py)"]:::backend
      PlatformImports["edX Platform Imports (platform_imports.py)"]:::backend
      Toggles["Feature Toggles (toggles.py)"]:::backend
      subgraph "Business Logic & Utilities"
        direction TB
        Data["Data Handling (data.py)"]:::backend
        TextUtils["Text Utils (text_utils.py)"]:::backend
        Utils["General Utils (utils.py)"]:::backend
        Constants["Constants (constants.py)"]:::backend
      end
      I18n["I18n Config (conf/locale/config.yaml)"]:::backend
      MgmtCmd["Management Cmd (retire_user_messages.py)"]:::backend
    end
  end

  DB["PostgreSQL DB"]:::persistence
  Migrations["DB Migrations"]:::persistence
  External["Chat Completion API"]:::external

  Browser -->|"AJAX /learning-assistant/api"| APIpy
  APIpy -->|uses| Serializers
  APIpy -->|queries| Models
  APIpy -->|calls| PluginsAPI
  APIpy -->|checks| Toggles
  APIpy -->|packages prompt via| Data
  Data --> TextUtils
  Data --> Constants
  APIpy -->|issues HTTP| External
  External -->|"response"| APIpy
  APIpy -->|persists message| Models
  APIpy -->|persist audit| Models
  Models --> DB
  Migrations --> DB
  MgmtCmd -.->|"periodic cleanup"| Models

  click Apps "https://github.com/edx/learning-assistant/blob/main/learning_assistant/apps.py"
  click URLRouting "https://github.com/edx/learning-assistant/blob/main/learning_assistant/urls.py"
  click APIpy "https://github.com/edx/learning-assistant/blob/main/learning_assistant/api.py"
  click Views "https://github.com/edx/learning-assistant/blob/main/learning_assistant/views.py"
  click Serializers "https://github.com/edx/learning-assistant/blob/main/learning_assistant/serializers.py"
  click Models "https://github.com/edx/learning-assistant/blob/main/learning_assistant/models.py"
  click Migrations "https://github.com/edx/learning-assistant/tree/main/learning_assistant/migrations/"
  click PluginsAPI "https://github.com/edx/learning-assistant/blob/main/learning_assistant/plugins_api.py"
  click PlatformImports "https://github.com/edx/learning-assistant/blob/main/learning_assistant/platform_imports.py"
  click Toggles "https://github.com/edx/learning-assistant/blob/main/learning_assistant/toggles.py"
  click Data "https://github.com/edx/learning-assistant/blob/main/learning_assistant/data.py"
  click TextUtils "https://github.com/edx/learning-assistant/blob/main/learning_assistant/text_utils.py"
  click Utils "https://github.com/edx/learning-assistant/blob/main/learning_assistant/utils.py"
  click Constants "https://github.com/edx/learning-assistant/blob/main/learning_assistant/constants.py"
  click I18n "https://github.com/edx/learning-assistant/blob/main/learning_assistant/conf/locale/config.yaml"
  click MgmtCmd "https://github.com/edx/learning-assistant/blob/main/learning_assistant/management/commands/retire_user_messages.py"

  classDef frontend fill:#85C1E9,stroke:#000,color:#000
  classDef backend fill:#82E0AA,stroke:#000,color:#000
  classDef persistence fill:#F7DC6F,stroke:#000,color:#000
  classDef external fill:#F5B041,stroke:#000,color:#000
```
