DB Modular Redesign: monolith → 8 bounded domains (migrations 0019–0028)

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AndresL230]

The epic cutover. Restructures the Postgres/Supabase schema from one offering-shaped courses table + a users mega-table into 8 bounded domains of typed tables with foreign keys, CHECK enums, a real terms entity, and one source of truth per fact — and rewires the entire backend onto it. Delivered schema-first (all migrations as one source of truth, then per-domain code slices).

What changed

• Academics: courses split into abstract courses + course_offerings (per term) + terms; user_courses → enrollments(offering_id). New resolver services/academics.py. API boundary still uses the abstract course_id; the split is resolved server-side.
• Identity: users slimmed; new user_profiles (1:1) holds name/profile fields (names still 🔒). New services/profiles.py for decrypted display names.
• Gradebook: re-keyed to enrollment_id (gradebook_categories, enrollment-keyed assignments); per-semester + cumulative GPA, bell-curve + drop-lowest; decrypt_numeric on 🔒 points.
• Knowledge Graph: stays on the abstract course (cumulative); graph_nodes.mastery_events JSON column → append-only node_mastery_events table; UNIQUE-backed node/edge upserts.
• Class Analytics: course_concept_stats/course_summary → offering_concept_stats/offering_summary (offering-keyed; free-text semester gone).
• Study: documents/notes/sessions/study_guides/flashcards re-keyed to offering_id + soft-delete + CHECK enums.
• Ops: feedback/issue_reports int PK → text PK + FKs.

How it was built & validated

Schema landed as migrations 0019–0028; code rewired in per-domain PRs that accumulated on this epic (#264 schema, #268 academics, #269–#274 the 6 domain slices, #275 reconciliation, #276 seed, #277/#278 staging fixes).

• ✅ 790 unit tests pass (mocked) · ruff clean
• ✅ 14/14 service checks pass against live staging seeded data (academics resolver, get_courses incl. multi-term CS101, get_graph, gradebook drop-lowest + decrypt → (92.0,'A-'), user_profiles decrypt, offering analytics, learn/graph-read).
• 🐛 Two real-DB bugs caught by seeding staging (invisible to mocked tests) and fixed in-epic: 0028 (vestigial course_offerings.course_code NOT NULL, would've broken add_course in prod) and the seed _exists_by id assumption.

For reviewers

• Developer migration guide: docs/db-modular-redesign-dev-guide.pdf (the id model, rename cheat-sheet, what to change). Design spec + epic plan under docs/superpowers/.
• Docs trued-up: CLAUDE.md, docs/architecture.md, README.md, ROADMAP.md.

⚠️ Before merging (prod cutover)

1. Deploy this branch to staging and HTTP-smoke-test the live app (enroll, courses-with-term, gradebook GPA, graph). Service-level E2E is green; the deployed-app pass is the last gate.
2. Full CI green on the merge.
3. Prod promotion (prod has no user data, only the catalog): migrate --baseline to record 0001–0018, then migrate to apply 0019+; the 0020 catalog transform is data-driven. Never run dashboard DDL.

Known follow-ups (non-blocking)

Frontend term picker (#260), gradescope code rewire (#265), schools population (school surfaces blank), duplicate subject-root hub for multi-term courses.

Summary by CodeRabbit

• New Features
  • Added term-aware academics (new /api/semesters) and updated courses/offerings behavior across gradebook, notes, study guides, flashcards, and graph.
  • Added semester-scoped gradebook details, including curve grading and credit-weighted GPA.
  • Added staging DB demo seeding and an opt-in staging E2E runner.
• Bug Fixes
  • Profile display names now consistently come from the dedicated public-profile data store.
  • Document and note deletion now uses soft delete.
  • Quiz difficulty is validated, and mastery updates now record reliably through the graph update flow.
• Documentation
  • Updated migration, architecture, and ops/staging guidance for ordered SQL migrations and the new schema conventions.

Resolved issues (auto-close on merge to main)

The DB modular redesign resolves these — semesters DB+backend, the missing indexes/FKs/UNIQUE-dedup, atomic mastery, graph write-integrity, social/students, and the staging catalog+environment:

Closes#100
Closes#128
Closes#137
Closes#138
Closes#158
Closes#160
Closes#161
Closes#176
Closes#177
Closes#178
Closes#179
Closes#180
Closes#181
Closes#195
Closes#247
Closes#258
Closes#259
Closes#266
Closes#267

Partially addressed (NOT closed — follow-ups remain): #142 (frontend term UI #139/#140/#141/#260), #265 (Gradescope code rewire), #126 (assignment-notes encryption + response-boundary leaks).

[coderabbitai]

Warning

Review limit reached

@AndresL230, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 49 minutes and 1 second. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 86250e2a-c43e-47fe-9830-6329f9404a91

📥 Commits

Reviewing files that changed from the base of the PR and between 77c4855 and afba99f.

📒 Files selected for processing (2)

• backend/db/e2e_checks/quiz.py
• backend/db/e2e_staging_http.py

📝 Walkthrough

Walkthrough

Backend guidance, schema migrations, services, routes, tests, and staging E2E checks were updated to match the modular database redesign. The PR shifts academics, identity, analytics, gradebook, graph, study, ops, and related docs/code paths to the new offering- and enrollment-based schema.

Changes

DB modular redesign

Layer / File(s)	Summary
Guidance and rollout docs CLAUDE.md, README.md, ROADMAP.md, docs/architecture.md, docs/staging/setup-checklist.md, docs/superpowers/plans/*, docs/superpowers/specs/*	Repository guidance, architecture notes, rollout instructions, roadmap entries, and redesign plans were updated for the modular schema work and staging E2E rollout.
Academics, identity, graph, and analytics code backend/db/migrations/0019_*.sql, 0020_*.sql, 0022_*.sql, 0023_*.sql, 0024_*.sql, backend/services/academics.py, backend/routes/academics.py, backend/main.py, backend/routes/auth.py, backend/routes/profile.py, backend/routes/onboarding.py, backend/services/profiles.py, backend/services/course_context_service.py, backend/services/graph_service.py, backend/agents/tools/graph_read.py, backend/routes/social.py, backend/services/users_search.py, backend/tests/test_academics.py, backend/tests/test_graph_service.py, backend/tests/test_graph_read_tools.py, backend/tests/test_shared_course_context.py, backend/tests/test_profile_routes.py, backend/tests/test_profiles_service.py, backend/tests/test_users_roster_auth.py, backend/tests/test_users_search.py, backend/tests/test_onboarding_routes.py, backend/tests/test_social_students.py	New academics helpers/routes, identity/profile reads and writes, graph/context offering lookups, analytics tables, and related test rewrites now use offerings, enrollments, and user_profiles.
Gradebook and graph mastery rules backend/db/migrations/0021_*.sql, backend/services/gradebook_service.py, backend/routes/gradebook.py, backend/models/__init__.py, backend/routes/quiz.py, backend/tests/test_gradebook_routes.py, backend/tests/test_gradebook_service.py, backend/tests/test_quiz_routes.py, backend/tests/test_response_decrypt_boundary.py	Gradebook routes, math, and models now resolve enrollments by semester and compute drop-lowest, curves, and GPA; graph mastery writes route through event rows.
Study, profile, social, and auth flows backend/db/migrations/0025_*.sql, backend/services/notes_service.py, backend/services/flashcard_import_service.py, backend/routes/documents.py, backend/routes/flashcards.py, backend/routes/learn.py, backend/routes/notes.py, backend/routes/study_guide.py, backend/tests/test_documents_routes.py, backend/tests/test_flashcard_import_routes.py, backend/tests/test_flashcard_import_service.py, backend/tests/test_learn_routes.py, backend/tests/test_notes_routes.py, backend/tests/test_notes_service.py, backend/tests/test_study_guide_routes.py, backend/tests/test_shared_course_context.py	Documents, notes, flashcards, study guides, and learn/session flows now key off offering_id, use soft deletes, and map back to abstract course ids where needed.
Ops cleanup and staging seed backend/db/migrations/0026_*.sql, backend/db/migrations/0027_*.sql, backend/db/migrations/0028_*.sql, backend/routes/feedback.py, backend/db/seed_staging.py, backend/tests/test_feedback_routes.py, backend/tests/test_seed_staging.py, backend/db/e2e_checks/*, backend/db/e2e_staging_http.py, backend/tests/conftest.py, backend/tests/test_e2e_staging.py	Feedback and issue-report IDs become explicit UUID text values, Gradescope sync tables are added, the staging seed writes deterministic demo rows, and staging-only HTTP E2E checks were added.

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related issues

• Rewire bell-curve + drop-lowest grading onto the redesigned gradebook (post-redesign) #266 — The updated gradebook math adds drop-lowest, curve, and GPA behavior that matches the grading redesign objective.
• [P2] Semesters: backend API — term list, gradebook/course scoping, GPA rollups #138 — The semester-aware academics split, enrollments, and GPA endpoints align with the term-aware gradebook and routing work.

Possibly related PRs

• SaplingLearn/Sapling#53 — Updates the same course-context service and context refresh flow that this PR extends to offering_id.
• SaplingLearn/Sapling#65 — Touches the same auth/profile code paths and encrypted profile-field handling moved to user_profiles.
• SaplingLearn/Sapling#67 — Updates the same document upload and persistence helpers that now key documents by offering_id.

Poem

A rabbit hopped through SQL snow,
Where offerings bloom and old paths go.
With curves and terms my whiskers twitch,
And profile names no longer glitch.
Hooray! 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main schema redesign and migration range.
Description check	✅ Passed	The description is detailed and covers the main changes and validation, but it doesn't follow the requested template headings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch epic/db-modular-redesign

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}