Skip to content

Monorepo Audit

Snapshot audit of the Open Learning Hub monorepo (Next.js 16 + React 19 + Tailwind v4, two Next apps + five workspace packages) with a prioritized backlog of improvement tickets.

Last updated: 2026-08-11 (closed out T-029 and T-030 ticket status/index drift after CI hardening rollout).

The full audit plan with evidence lives in the originating proposal (.cursor/plans/monorepo_audit_and_opportunities_*.plan.md). This folder is the living, ticket-level view that we amend as we work.

Canonical audit references

Ratings recap

# Category Rating
1 Architecture (CMS/LMS consistency) 7 / 10
2 Type Safety 8 / 10
3 Code Organization 7 / 10
4 Testing 7 / 10
5 Security 6.5 / 10
6 API Design 6.5 / 10
7 Developer Experience 8.5 / 10
8 Maintainability 7 / 10
9 Monorepo Architecture 9 / 10
10 Code Coverage (enforcement) 5 / 10

Composite: ~7.0 / 10.

Standing decisions

  • CMS API-first vs LMS server-actions-first is a settled strategic choice. Tickets harmonize primitives (errors, headers, password, logger) but do not force convergence of mutation transport.
  • Remaining @open-learning-hub/server package scope (T-006) is deferred. T-009 (CMS server-only guards) is deferred and bundled with T-006 — reactivate when @open-learning-hub/server extraction is reprioritized. T-015 (PostHog observability + product analytics) is active. Tickets T-006, T-009, T-018, T-021–T-022, and T-024–T-025 live under tickets/deferred/.
  • T-020 (CMS structured logger) is now implemented via Option A with a parity backport to LMS src/lib/log.ts to avoid cross-app drift. The canonical contract is .cursor/rules/091-structured-logging.mdc, including the edge-safe console.* emit decision.
  • Wave 2: T-016 (PostgreSQL pool config) and T-023 (health check endpoint) are done. T-017 is active (in-progress) for E2E stabilization and CI re-enablement. T-018, T-021–T-022, and T-024–T-025 remain deferred. T-019 (npm Dependabot) is done.
  • npm run check is the gate after every ticket per .cursor/rules/070-code-quality.mdc.
  • CMS token_version (T-002): Pure grants (role assignment, tenant membership add) do not invalidate JWTs by default. Revocations, deactivation, and password reset bump users.token_version immediately. We explicitly rejected bumping on every grant — see T-002 notes.

Ticket status

Status legend: proposed · in-progress · blocked · done · deferred.

ID Title Priority Area Apps Status
T-001 Wire LMS security headers P1 security lms done
T-002 CMS JWT invalidation via token_version P1 security cms done
T-003 Standardize LMS API/action error contract P1 api lms done
T-004 Enable Vitest coverage in CI P2 testing cms, lms done
T-005 LMS mutation test sweep P1 testing lms done
T-006 @open-learning-hub/server shared package deferred monorepo cms, lms deferred
T-007 Enable noUncheckedIndexedAccess in apps P2 types cms, lms done
T-008 Stop excluding test files from CMS typecheck P2 dx cms done
T-009 CMS server-only guards deferred security cms deferred
T-010 Centralize Props/domain types (or update rule) P3 types cms, lms done
T-011 Split large CMS files P3 refactor cms done
T-012 Shared password helper P2 security lms done
T-013 LMS OpenAPI generation P3 api lms done
T-014 Implement Upstash rate-limit driver P1 security cms, lms done
T-015 PostHog observability + product analytics P1 observability cms, lms in-progress
T-016 PostgreSQL connection pool configuration P1 resilience lms, cms done
T-017 E2E test stability & CI re-enablement P2 testing lms, cms in-progress
T-018 Pre-commit hooks (lint-staged + Husky) deferred dx cms, lms deferred
T-019 Automated npm dependency updates P3 dx cms, lms, packages/* done
T-020 CMS structured logger P2 observability cms, lms done
T-021 CMS environment validation centralization deferred dx cms deferred
T-022 Next.js middleware for LMS auth & tenancy deferred architecture lms deferred
T-023 Health check endpoint P2 resilience lms, cms done
T-024 Root TypeScript project references deferred dx all deferred
T-025 Production environment templates deferred dx lms, cms deferred
T-026 Email platform roadmap P2 monorepo lms, cms, packages/email proposed
T-027 Maintain CMS and LMS drift matrix P2 monorepo lms, cms, packages/ui, packages/design-tokens in-progress
T-028 Centralize seed/demo/test passwords via env vars P2 security lms, cms done
T-029 Align project publication semantics P2 api lms, cms done
T-030 Promote Playwright CI jobs from non-blocking to blocking P2 testing lms, cms done

Execution order

Done: T-001, T-002, T-003, T-004, T-005, T-007, T-008, T-010, T-011, T-012, T-013, T-014, T-016, T-019, T-020, T-023, T-028, T-029, T-030.

Deferred: T-006, T-009 (bundled with T-006), T-018, T-021–T-022, T-024–T-025.

Active: T-015, T-017, and T-027 are in progress. T-026 is proposed.

Working with tickets

  • Copy _template.md for any new ticket and assign the next free T-NNN id.
  • Update the ticket's status and append a dated entry to the Notes / decisions log as work progresses.
  • Keep evidence and file links inside the ticket so the README stays a one-glance index.