# openstax/tutor-server architecture

> Architecture diagram of the GitHub repository openstax/tutor-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openstax/tutor-server
- Repository: https://github.com/openstax/tutor-server

## Overview

OpenStax Tutor is a Rails backend for managing courses, course membership, learning tasks, and related services. One evidenced user workflow is enrollment: a learner submits an enrollment request, the API validates its parameters, creates an enrollment change, and an authorized user can approve it to process the membership change. The tree also shows distinct content, course, task, research, and LMS capabilities. Those branches are represented as subsystems, but their internal connections are not established by the sampled source; dashed edges mark those uncertain links.

Main entry points: [`app/controllers/api/v1/enrollment_controller.rb`](https://github.com/openstax/tutor-server/blob/main/app/controllers/api/v1/enrollment_controller.rb) (Enrollment API), [`app/subsystems/course_membership/process_enrollment_change.rb`](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/process_enrollment_change.rb) (Process enrollment change), [`app/subsystems/course_membership/models/enrollment_change.rb`](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/models/enrollment_change.rb) (Membership records), [`app/controllers/research/studies_controller.rb`](https://github.com/openstax/tutor-server/blob/main/app/controllers/research/studies_controller.rb) (Study management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_course["Courses and membership"]
  node_validate_enrollment["Validate enrollment"]
  node_process_enrollment["Process enrollment change"]
  node_membership_models[("Membership records")]
  node_course_profile[("Course profiles<br/>[course.rb]")]
  node_course_membership["Course membership<br/>[add_student.rb]"]
  node_course_content["Course content links"]
end

subgraph group_learning["Learning content and tasks"]
  node_content_import["Content import<br/>[import_book.rb]"]
  node_content_catalog[("Content catalog<br/>[ecosystem.rb]")]
  node_task_distribution["Task distribution"]
  node_task_runtime["Task execution<br/>[get_tasks.rb]"]
  node_preview_work["Preview course work"]
end

subgraph group_research["Research"]
  node_research_studies["Study management"]
  node_cohort_membership["Cohort membership"]
  node_survey_workflow["Survey workflow<br/>[complete_survey.rb]"]
end

subgraph group_integration["LMS integration"]
  node_lms_launch["LMS launch<br/>[launch.rb]"]
  node_lms_controller["LMS entry point<br/>[lms_controller.rb]"]
  node_lms_courses["LMS course API"]
end

subgraph group_api["API and access"]
  node_api_enrollment["Enrollment API"]
  node_enrollment_policy["Enrollment access policy"]
  node_enrollment_repr["Enrollment representations"]
end

node_learner(("Learner"))
node_postgres[("PostgreSQL")]
node_lms_provider(("Learning platform"))

node_learner -->|"requests enrollment"| node_api_enrollment
node_api_enrollment -->|"validates parameters"| node_validate_enrollment
node_api_enrollment -->|"processes approval"| node_process_enrollment
node_api_enrollment -->|"checks approval"| node_enrollment_policy
node_api_enrollment -->|"renders enrollment"| node_enrollment_repr
node_validate_enrollment -.->|"validates against"| node_membership_models
node_process_enrollment -.->|"updates membership"| node_membership_models
node_process_enrollment -.->|"changes enrollment"| node_course_membership
node_course_profile -.->|"has membership"| node_course_membership
node_course_content -.->|"uses ecosystem"| node_content_catalog
node_content_import -.->|"imports content"| node_content_catalog
node_task_distribution -.->|"assigns tasks"| node_task_runtime
node_preview_work -.->|"works preview tasks"| node_task_runtime
node_research_studies -.->|"manages cohorts"| node_cohort_membership
node_research_studies -.->|"manages surveys"| node_survey_workflow
node_lms_provider -.->|"launches course"| node_lms_controller
node_lms_controller -.->|"handles launch"| node_lms_launch
node_lms_courses -.->|"pairs courses"| node_lms_launch
node_membership_models -.->|"persists records"| node_postgres

click node_api_enrollment "https://github.com/openstax/tutor-server/blob/main/app/controllers/api/v1/enrollment_controller.rb"
click node_enrollment_policy "https://github.com/openstax/tutor-server/blob/main/app/access_policies/enrollment_change_access_policy.rb"
click node_enrollment_repr "https://github.com/openstax/tutor-server/blob/main/app/representers/api/v1/enrollment_change_representer.rb"
click node_validate_enrollment "https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/validate_enrollment_parameters.rb"
click node_process_enrollment "https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/process_enrollment_change.rb"
click node_membership_models "https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/models/enrollment_change.rb"
click node_course_profile "https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_profile/models/course.rb"
click node_course_membership "https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/add_student.rb"
click node_course_content "https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_content/add_ecosystem_to_course.rb"
click node_content_import "https://github.com/openstax/tutor-server/blob/main/app/subsystems/content/import_book.rb"
click node_content_catalog "https://github.com/openstax/tutor-server/blob/main/app/subsystems/content/models/ecosystem.rb"
click node_task_distribution "https://github.com/openstax/tutor-server/blob/main/app/routines/distribute_tasks.rb"
click node_task_runtime "https://github.com/openstax/tutor-server/blob/main/app/subsystems/tasks/get_tasks.rb"
click node_preview_work "https://github.com/openstax/tutor-server/blob/main/app/routines/work_preview_course_tasks.rb"
click node_research_studies "https://github.com/openstax/tutor-server/blob/main/app/controllers/research/studies_controller.rb"
click node_cohort_membership "https://github.com/openstax/tutor-server/blob/main/app/subsystems/research/cohort_membership_manager.rb"
click node_survey_workflow "https://github.com/openstax/tutor-server/blob/main/app/subsystems/research/complete_survey.rb"
click node_lms_launch "https://github.com/openstax/tutor-server/blob/main/app/subsystems/lms/launch.rb"
click node_lms_controller "https://github.com/openstax/tutor-server/blob/main/app/controllers/lms_controller.rb"
click node_lms_courses "https://github.com/openstax/tutor-server/blob/main/app/controllers/api/v1/lms/courses_controller.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_validate_enrollment,node_process_enrollment,node_membership_models,node_course_profile,node_course_membership,node_course_content toneBlue
class node_content_import,node_content_catalog,node_task_distribution,node_task_runtime,node_preview_work,node_postgres toneAmber
class node_research_studies,node_cohort_membership,node_survey_workflow toneMint
class node_lms_launch,node_lms_controller,node_lms_courses toneRose
class node_api_enrollment,node_enrollment_policy,node_enrollment_repr,node_learner,node_lms_provider toneIndigo
```

## Components

### Courses and membership

- [Validate enrollment](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/validate_enrollment_parameters.rb): `app/subsystems/course_membership/validate_enrollment_parameters.rb`
- [Process enrollment change](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/process_enrollment_change.rb): `app/subsystems/course_membership/process_enrollment_change.rb`
- [Membership records](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/models/enrollment_change.rb): `app/subsystems/course_membership/models/enrollment_change.rb`
- [Course profiles](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_profile/models/course.rb): `app/subsystems/course_profile/models/course.rb`
- [Course membership](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_membership/add_student.rb): `app/subsystems/course_membership/add_student.rb`
- [Course content links](https://github.com/openstax/tutor-server/blob/main/app/subsystems/course_content/add_ecosystem_to_course.rb): `app/subsystems/course_content/add_ecosystem_to_course.rb`

### Learning content and tasks

- [Content import](https://github.com/openstax/tutor-server/blob/main/app/subsystems/content/import_book.rb): `app/subsystems/content/import_book.rb`
- [Content catalog](https://github.com/openstax/tutor-server/blob/main/app/subsystems/content/models/ecosystem.rb): `app/subsystems/content/models/ecosystem.rb`
- [Task distribution](https://github.com/openstax/tutor-server/blob/main/app/routines/distribute_tasks.rb): `app/routines/distribute_tasks.rb`
- [Task execution](https://github.com/openstax/tutor-server/blob/main/app/subsystems/tasks/get_tasks.rb): `app/subsystems/tasks/get_tasks.rb`
- [Preview course work](https://github.com/openstax/tutor-server/blob/main/app/routines/work_preview_course_tasks.rb): `app/routines/work_preview_course_tasks.rb`

### Research

- [Study management](https://github.com/openstax/tutor-server/blob/main/app/controllers/research/studies_controller.rb): `app/controllers/research/studies_controller.rb`
- [Cohort membership](https://github.com/openstax/tutor-server/blob/main/app/subsystems/research/cohort_membership_manager.rb): `app/subsystems/research/cohort_membership_manager.rb`
- [Survey workflow](https://github.com/openstax/tutor-server/blob/main/app/subsystems/research/complete_survey.rb): `app/subsystems/research/complete_survey.rb`

### LMS integration

- [LMS launch](https://github.com/openstax/tutor-server/blob/main/app/subsystems/lms/launch.rb): `app/subsystems/lms/launch.rb`
- [LMS entry point](https://github.com/openstax/tutor-server/blob/main/app/controllers/lms_controller.rb): `app/controllers/lms_controller.rb`
- [LMS course API](https://github.com/openstax/tutor-server/blob/main/app/controllers/api/v1/lms/courses_controller.rb): `app/controllers/api/v1/lms/courses_controller.rb`

### API and access

- [Enrollment API](https://github.com/openstax/tutor-server/blob/main/app/controllers/api/v1/enrollment_controller.rb): `app/controllers/api/v1/enrollment_controller.rb`
- [Enrollment access policy](https://github.com/openstax/tutor-server/blob/main/app/access_policies/enrollment_change_access_policy.rb): `app/access_policies/enrollment_change_access_policy.rb`
- [Enrollment representations](https://github.com/openstax/tutor-server/blob/main/app/representers/api/v1/enrollment_change_representer.rb): `app/representers/api/v1/enrollment_change_representer.rb`

### Other components

- **Learner**
- **PostgreSQL**
- **Learning platform**

## Connections

- Learner → Enrollment API: requests enrollment (evidence: `app/controllers/api/v1/enrollment_controller.rb`)
- Enrollment API → Validate enrollment: validates parameters (evidence: `app/controllers/api/v1/enrollment_controller.rb`)
- Enrollment API → Process enrollment change: processes approval (evidence: `app/controllers/api/v1/enrollment_controller.rb`)
- Enrollment API → Enrollment access policy: checks approval (evidence: `app/controllers/api/v1/enrollment_controller.rb`)
- Enrollment API → Enrollment representations: renders enrollment (evidence: `app/controllers/api/v1/enrollment_controller.rb`)
- Validate enrollment → Membership records: validates against
- Process enrollment change → Membership records: updates membership
- Process enrollment change → Course membership: changes enrollment
- Course profiles → Course membership: has membership
- Course content links → Content catalog: uses ecosystem
- Content import → Content catalog: imports content
- Task distribution → Task execution: assigns tasks
- Preview course work → Task execution: works preview tasks
- Study management → Cohort membership: manages cohorts
- Study management → Survey workflow: manages surveys
- Learning platform → LMS entry point: launches course
- LMS entry point → LMS launch: handles launch
- LMS course API → LMS launch: pairs courses
- Membership records → PostgreSQL: persists records
