> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hawkings.education/llms.txt
> Use this file to discover all available pages before exploring further.

# Data model

> The full graph: workspaces → courses → cohorts → lessons → activities → questions.

The Hawkings data model is intentionally familiar to anyone who has
shipped against Canvas, Moodle, or Google Classroom. Three things make
it different:

1. **Courses and cohorts are separated.** A `Course` is the syllabus —
   the curriculum, the lesson tree, the rubrics. A `Cohort` is one
   *run* of that course for a specific group. Same syllabus, three
   semesters → one Course, three Cohorts.
2. **Activities and assignments are different.** Activities are inline
   exercises (quizzes, flashcards, short-answer prompts). Assignments
   are gradable artefacts, with submissions, due dates, and rubrics.
3. **Everything has an AI mode.** Anywhere you can author by hand, you
   can also generate with `*.generate*()`.

## The graph

```
Workspace
  ├─ Users
  │   ├─ Students  (role: student)
  │   └─ Teachers  (role: teacher)
  │
  └─ Course (the syllabus)
      └─ Cohort (one run of the course)
          ├─ enrolled Users
          └─ Unit (optional grouping)
              └─ Lesson
                  ├─ LessonContent  (long-form HTML reading)
                  ├─ Activity
                  │   └─ Question
                  └─ Assignment
                      └─ Submission  (per-student attempt)
```

## Resources at a glance

<ResponseField name="Workspace" type="object">
  A tenant. Holds users and courses. A user can belong to many
  workspaces (each gets a separate API key).
</ResponseField>

<ResponseField name="Course" type="object">
  The curriculum: name, description, language, target hours, AI
  instructions. Contains cohorts.

  A `Course` has no students by itself. To enroll students, create a
  `Cohort`.
</ResponseField>

<ResponseField name="Cohort" type="object">
  A run of a course for a group of students at a moment in time.
  Carries the actual lessons, students, teachers, assignments, and
  submissions.

  Multiple cohorts of the same course are common: spring vs. fall, group
  A vs. group B, English-track vs. Spanish-track.
</ResponseField>

<ResponseField name="Unit" type="object">
  Optional. Groups lessons inside a cohort. If you don't need them,
  ignore them — lessons can hang directly off the cohort.
</ResponseField>

<ResponseField name="Lesson" type="object">
  The atomic learning unit. Has a name, a type, a position, and holds:

  * `LessonContent` (the long-form reading)
  * `Activity` (one or many — the inline exercises)
  * `Assignment` (zero or one — the gradable item)
</ResponseField>

<ResponseField name="LessonContent" type="object">
  HTML reading material. AI-generated, hand-written, or imported from
  PDF / DOCX / SCORM.
</ResponseField>

<ResponseField name="Activity" type="object">
  One of [22 types](/concepts/activities-and-questions): `quiz`,
  `flashcard`, `podcast`, `diagram`, `glossary`, `expand`, `explain`…
  All created with the same `activities.create()` call.
</ResponseField>

<ResponseField name="Question" type="object">
  A single question inside an Activity. Quizzes have many; flashcards
  have one (the front/back pair). Each Question can be evaluated
  individually or as part of the parent Activity.
</ResponseField>

<ResponseField name="Assignment" type="object">
  A gradable task tied to a lesson. Has a rubric, a due date, optional
  AI evaluator config.
</ResponseField>

<ResponseField name="Submission" type="object">
  A student's response to an assignment, plus its grade. The grade may
  be human, AI, or both. AI grading attaches a `grading_rationale`.
</ResponseField>

<ResponseField name="User" type="object">
  Anyone with access to a workspace. The `role` field is one of
  `student`, `teacher`, `manager`, `admin`. There are sugar resources
  `students` and `teachers` for the common filters.
</ResponseField>

## Identifiers

| Resource      | Prefix | Example             |
| ------------- | ------ | ------------------- |
| Workspace     | `wks_` | `wks_01HX9N5AB3...` |
| Course        | `crs_` | `crs_01HX9N5AB3...` |
| Cohort        | `coh_` | `coh_01HX9N5AB3...` |
| Unit          | `uni_` | `uni_01HX9N5AB3...` |
| Lesson        | `lsn_` | `lsn_01HX9N5AB3...` |
| LessonContent | `lct_` | `lct_01HX9N5AB3...` |
| Activity      | `act_` | `act_01HX9N5AB3...` |
| Question      | `que_` | `que_01HX9N5AB3...` |
| Assignment    | `asg_` | `asg_01HX9N5AB3...` |
| Submission    | `sub_` | `sub_01HX9N5AB3...` |
| User          | `usr_` | `usr_01HX9N5AB3...` |

IDs are immutable, URL-safe, and sortable by creation time.

## Mapping from other LMSs

| Canvas     | Moodle     | Google Classroom | **Hawkings**            |
| ---------- | ---------- | ---------------- | ----------------------- |
| Account    | Site       | Domain           | Workspace               |
| Course     | Course     | Course           | Cohort                  |
| Module     | Section    | (n/a)            | Unit                    |
| (n/a)      | Activity   | (n/a)            | Lesson                  |
| Assignment | Assignment | Assignment       | Assignment              |
| Submission | Submission | Submission       | Submission              |
| Quiz       | Quiz       | Form Quiz        | Activity (`type: quiz`) |

A `Course` (Hawkings) has no direct analogue in those systems — they
treat the syllabus and the run as one object. The split is what lets you
re-run a course without re-authoring it.