ulivargas/classroomio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5a8f50f67b0cb04900678b8e836f6128f19db593
classroomio/prd/programs
T
History

README.md

Programs PRD

Purpose

Enable instructors and org admins to group multiple courses — along with shared announcements, files, and community discussions — into a single program. Enrolling a student in a program auto-enrolls them in every course inside it, eliminating the need to manage per-course enrollment manually when delivering a structured program.

Problem Statement

Currently, ClassroomIO has no entity above the individual course. Every course has its own independent enrollment roster. This creates several pain points:

  • An instructor running a program (e.g., a bootcamp, onboarding track, or certification pathway) must enroll students in each constituent course one by one.
  • There is no shared space for program-wide announcements, files, or discussions that span multiple courses.
  • Students cannot see a unified "program" view in the LMS — they only see a flat list of individual courses.
  • Org admins have no way to bundle courses for a specific cohort of learners (e.g., "Q1 2026 New Hire Onboarding") without creating separate organizations or duplicating content.

Confirmed Decisions

  1. Terminology: "Program" in both the instructor-facing admin UI and the student-facing LMS.
  2. Auto-enrollment: Joining a program automatically creates groupmember records for every course inside the program. Removing a student from a program does not remove them from individual course groups, preserving their submission and progress data.
  3. Shared materials: Each program has three shared material surfaces: announcements (instructor-authored posts), a file library, and a community Q&A board.
  4. Many-to-many courses: A course can belong to multiple programs. Courses and programs are independent entities linked by a join table.
  5. LMS visibility: Programs are visible to students in the LMS under a dedicated "Programs" section. Students see enrolled programs and can navigate courses from within a program hub page.
  6. Roles: Program roles mirror the existing system (ADMIN/roleId 1, TUTOR/roleId 2, STUDENT/roleId 3). Program admins and tutors can manage the program; program students get read access to materials.
  7. Program status: Programs can be ACTIVE, INACTIVE, or ARCHIVED. INACTIVE programs are hidden from students in the LMS but preserved for instructors. ARCHIVED programs are soft-deleted and hidden everywhere.
  8. Course independence: Courses in a program remain fully independent. A student enrolled in a program is a regular groupmember in each course — existing course pages, progress tracking, submissions, and grading are unchanged.
  9. Community reuse: The existing community_question table gains a nullable programId FK. Program-level Q&A behaves identically to course-level community Q&A but scoped to the program.

Current-State Audit

Capability Current State Notes
Organization structure organization → group (1:1 with course) → course No intermediate grouping layer above course
Course enrollment groupmember rows per course's group Per-course, no bulk enrollment mechanism
Student LMS view Flat list of enrolled courses under /lms/mylearning No program/program concept
Community Q&A community_question.courseId scoped Reusable with additional programId FK
Shared file library Per-course via assets table; no org-wide shared files New program_file table needed
Announcements Per-course course_newsfeed New program_announcement table needed
Org admin navigation "Courses" section listing all courses "Programs" nav item needed
LMS navigation Home, My Learning, Exercises, Community, Explore, Settings "Programs" nav item needed
Enrollment service enrollInCourse() in apps/api/src/services/course/invite.ts Must be called per-course when adding program member

Key insight: Because enrollment = groupmember rows per course, adding a student to a program is purely a matter of calling the existing enrollment logic for each course in the program within a single transaction. No course-level schema changes are needed.

Product Goals

  1. Org admins and instructors can create a program, add courses to it, and manage program membership from the admin dashboard.
  2. Adding a student to a program auto-enrolls them in all courses currently in the program.
  3. Adding a new course to an existing program auto-enrolls all current program students in that course.
  4. Each program has a shared announcements feed, file library, and community board visible to all program members.
  5. Students can see their enrolled programs in the LMS with a unified hub view showing all courses, announcements, and files.
  6. Programs without students, and courses outside any program, continue to work exactly as they do today (zero regression).

Non-Goals (v1)

  • Program-level invite links (v1 enrollment is admin-managed; students cannot self-enroll in a program via a token).
  • Program-specific exercise deadlines or content overrides (courses are shared as-is).
  • Program progress analytics aggregated across all courses (available per-course; cross-course aggregation is a future improvement).
  • Removing a student from a program also unenrolling them from individual courses (data preservation is the default).
  • Program templates or program cloning.
  • Public/discoverable program landing pages (programs are private to org members).
  • Billing or pricing at the program level.
  • Program-level attendance tracking separate from per-course attendance.

Data Sources Checked

  • packages/db/src/schema.ts — all table definitions and constraint patterns
  • apps/api/src/services/course/course.ts — course creation flow
  • apps/api/src/services/course/invite.ts — enrollment flow (enrollInCourse)
  • apps/api/src/routes/course/course.ts — course router and sub-router mounting
  • apps/api/src/app.ts — top-level router registration
  • packages/db/src/queries/course/people.ts — group member management
  • packages/db/src/queries/group/group.ts — group/member queries
  • packages/db/src/queries/community/community.ts — community Q&A pattern
  • apps/dashboard/src/lib/features/lms/ — LMS navigation and pages
  • apps/dashboard/src/lib/features/org/ — org admin navigation
  • apps/dashboard/src/routes/lms/ — LMS SvelteKit routes
  • apps/dashboard/src/routes/courses/ — course admin SvelteKit routes

Functional Requirements

1. Program CRUD (Admin)

  • Org admins can create a program with: name (required), description (optional), cover image (optional).
  • Programs can be updated (name, description, cover image, status).
  • Archiving a program sets status = 'ARCHIVED' and hides it from all views. Archived programs can be restored.
  • A program belongs to exactly one organization.
  • Program names do not need to be unique within an org (unlike course slugs), but should be descriptive.

2. Course Management in a Program (Admin)

  • Org admins and program tutors can add existing org courses to a program.
  • A course can belong to multiple programs simultaneously.
  • Adding a course to a program triggers auto-enrollment: all existing STUDENT program members are enrolled in the new course (a groupmember row is created in the course's group for each student not already enrolled).
  • Removing a course from a program does not unenroll any students from that course. Their progress and submissions are preserved.
  • Courses within a program are ordered (integer order field) so instructors can sequence them.

3. Program Membership (Admin)

  • Org admins can add members to a program by profile ID or email, assigning them a role (ADMIN, TUTOR, or STUDENT).
  • Adding a STUDENT member triggers auto-enrollment: a groupmember row is created in every course currently in the program (skipping courses the student is already enrolled in; idempotent).
  • Adding an ADMIN or TUTOR member does not auto-enroll them in courses (their course-level permissions are managed separately via course membership).
  • Removing a member from a program removes the program_member row only. Individual groupmember rows in courses are left intact, preserving submissions, grades, and progress.
  • Batch add: admins can add multiple members at once (array of { email, roleId } pairs).

4. Program Announcements (Admin + LMS)

  • Program admins and tutors can post announcements to the program feed.
  • Announcements have a title and a rich-text body.
  • Announcements are visible to all program members (students, tutors, and admins) in both the admin program view and the LMS program hub.
  • Students cannot post announcements (read-only for students).
  • Announcements are ordered by createdAt descending (newest first).

5. Program File Library (Admin + LMS)

  • Program admins and tutors can upload files to the program file library.
  • Each file record stores: name, URL (stored via the existing presigned upload flow), MIME type, size, uploader profile ID.
  • All program members can view and download files.
  • Only program admins and tutors can delete files.

6. Program Community (Admin + LMS)

  • Program-level community Q&A reuses the existing community_question / community_answer infrastructure.
  • A nullable programId FK is added to community_question. Questions with programId set are program-scoped (not visible on the course-level community board).
  • All program members can post questions and answers in the program community.
  • The existing voting, commenting, and answer-acceptance behavior is unchanged.

7. LMS — My Programs (Student)

  • A "Programs" nav item appears in the LMS sidebar when the student is enrolled in at least one program.
  • The /lms/programs page lists all programs the student is enrolled in.
  • Each program card shows: program name, cover image, number of courses, brief description.
  • Clicking a program opens the program hub page.

8. LMS — Program Hub (Student)

  • The program hub at /lms/programs/[programId] is the student's central page for a program.
  • It is divided into three tabs or sections:
    • Courses: All courses in the program, each with the student's individual progress bar and a direct link to the course. Courses are shown in the instructor-defined order.
    • Announcements: Program announcements in reverse-chronological order (read-only for students).
    • Resources: The program file library (download only) and a link to the program community board.
  • The program community board lives at /lms/programs/[programId]/community and behaves identically to the existing course community pages.

9. Admin — Programs Section

  • "Programs" is added as a top-level nav item in the org admin sidebar, alongside "Courses".
  • The /courses/programs page lists all org programs with name, course count, student count, and status badge.
  • A "Create Program" button opens a creation form.
  • Each program links to a program detail view with sub-pages: Overview, Courses, People, Announcements, Files.

10. Access Control

  • Only ADMIN and TUTOR role members of a program (or org admins) can manage program content and membership.
  • Students can read announcements and files, participate in the community, and view the course list.
  • A student who is removed from the org loses access to all program content.
  • An INACTIVE program is hidden from students in the LMS but all data is preserved.

Technical Design

Data Model

New Enum: PROGRAM_STATUS

// packages/db/src/schema.ts
export const programStatus = pgEnum('PROGRAM_STATUS', ['ACTIVE', 'INACTIVE', 'ARCHIVED']);

New Table: program

// packages/db/src/schema.ts
export const lmsProgram = pgTable(
  'program',
  {
    id: uuid()
      .default(sql`gen_random_uuid()`)
      .primaryKey()
      .notNull(),
    createdAt: timestamp('created_at', { withTimezone: true, mode: 'string' }).defaultNow().notNull(),
    updatedAt: timestamp('updated_at', { withTimezone: true, mode: 'string' }).defaultNow(),
    organizationId: uuid('organization_id').notNull(),
    name: varchar().notNull(),
    description: text(),
    coverImage: text('cover_image'),
    status: programStatus().default('ACTIVE').notNull(),
    createdByProfileId: uuid('created_by_profile_id')
  },
  (table) => [
    foreignKey({
      columns: [table.organizationId],
      foreignColumns: [organization.id],
      name: 'class_organization_id_fkey'
    }).onDelete('cascade'),
    foreignKey({
      columns: [table.createdByProfileId],
      foreignColumns: [profile.id],
      name: 'class_created_by_profile_id_fkey'
    }),
    index('idx_program_organization_id').on(table.organizationId)
  ]
);

New Table: program_course

Many-to-many join between program and course, with an instructor-controlled display order.

// packages/db/src/schema.ts
export const programCourse = pgTable(
  'program_course',
  {
    id: uuid()
      .default(sql`gen_random_uuid()`)
      .primaryKey()
      .notNull(),
    programId: uuid('program_id').notNull(),
    courseId: uuid('course_id').notNull(),
    order: integer().default(0).notNull(),
    addedAt: timestamp('added_at', { withTimezone: true, mode: 'string' }).defaultNow().notNull()
  },
  (table) => [
    foreignKey({
      columns: [table.programId],
      foreignColumns: [lmsProgram.id],
      name: 'program_course_class_id_fkey'
    }).onDelete('cascade'),
    foreignKey({
      columns: [table.courseId],
      foreignColumns: [course.id],
      name: 'program_course_course_id_fkey'
    }).onDelete('cascade'),
    unique('program_course_class_id_course_id_unique').on(table.programId, table.courseId),
    index('idx_program_course_class_id').on(table.programId)
  ]
);

New Table: program_member

Membership roster for a program. Does not replace groupmember — it is a separate layer.

// packages/db/src/schema.ts
export const programMember = pgTable(
  'program_member',
  {
    id: uuid()
      .default(sql`gen_random_uuid()`)
      .primaryKey()
      .notNull(),
    programId: uuid('program_id').notNull(),
    profileId: uuid('profile_id'),
    roleId: integer('role_id').notNull(),
    email: text(),
    createdAt: timestamp('created_at', { withTimezone: true, mode: 'string' }).defaultNow().notNull()
  },
  (table) => [
    foreignKey({
      columns: [table.programId],
      foreignColumns: [lmsProgram.id],
      name: 'program_member_class_id_fkey'
    }).onDelete('cascade'),
    foreignKey({
      columns: [table.profileId],
      foreignColumns: [profile.id],
      name: 'program_member_profile_id_fkey'
    }),
    foreignKey({
      columns: [table.roleId],
      foreignColumns: [role.id],
      name: 'program_member_role_id_fkey'
    }),
    unique('program_member_class_id_profile_id_unique').on(table.programId, table.profileId),
    index('idx_program_member_class_id').on(table.programId),
    index('idx_program_member_profile_id').on(table.profileId)
  ]
);

New Table: program_announcement

// packages/db/src/schema.ts
export const programAnnouncement = pgTable(
  'program_announcement',
  {
    id: uuid()
      .default(sql`gen_random_uuid()`)
      .primaryKey()
      .notNull(),
    programId: uuid('program_id').notNull(),
    authorProfileId: uuid('author_profile_id'),
    title: varchar().notNull(),
    body: text(),
    createdAt: timestamp('created_at', { withTimezone: true, mode: 'string' }).defaultNow().notNull(),
    updatedAt: timestamp('updated_at', { withTimezone: true, mode: 'string' }).defaultNow()
  },
  (table) => [
    foreignKey({
      columns: [table.programId],
      foreignColumns: [lmsProgram.id],
      name: 'program_announcement_class_id_fkey'
    }).onDelete('cascade'),
    foreignKey({
      columns: [table.authorProfileId],
      foreignColumns: [profile.id],
      name: 'program_announcement_author_profile_id_fkey'
    }),
    index('idx_program_announcement_class_id').on(table.programId)
  ]
);

New Table: program_file

// packages/db/src/schema.ts
export const programFile = pgTable(
  'program_file',
  {
    id: uuid()
      .default(sql`gen_random_uuid()`)
      .primaryKey()
      .notNull(),
    programId: uuid('program_id').notNull(),
    uploadedByProfileId: uuid('uploaded_by_profile_id'),
    name: varchar().notNull(),
    url: text().notNull(),
    mimeType: varchar('mime_type'),
    size: integer(),
    createdAt: timestamp('created_at', { withTimezone: true, mode: 'string' }).defaultNow().notNull()
  },
  (table) => [
    foreignKey({
      columns: [table.programId],
      foreignColumns: [lmsProgram.id],
      name: 'program_file_class_id_fkey'
    }).onDelete('cascade'),
    foreignKey({
      columns: [table.uploadedByProfileId],
      foreignColumns: [profile.id],
      name: 'program_file_uploaded_by_profile_id_fkey'
    }),
    index('idx_program_file_class_id').on(table.programId)
  ]
);

Modified Table: community_question

Add a nullable programId FK so community questions can be scoped to a program:

// Add to community_question table columns:
programId: uuid('program_id')

// Add to community_question table constraints:
foreignKey({
  columns: [table.programId],
  foreignColumns: [lmsProgram.id],
  name: 'community_question_class_id_fkey'
}).onDelete('cascade')

When programId is set, the question is program-scoped. When courseId is set, it is course-scoped. The two are mutually exclusive in practice (enforced at the service layer).

Relationship Diagram

organization
  └── program
        ├── program_course  ──────────────────────→  course
        │     (order, addedAt)                        └── group → groupmember ← (auto-created)
        ├── program_member  ──────────────────────→  profile
        │     (roleId: ADMIN/TUTOR/STUDENT)
        ├── program_announcement
        │     (title, body, authorProfileId)
        ├── program_file
        │     (name, url, mimeType, size)
        └── community_question (programId set)
              └── community_answer

Migration

File: packages/db/src/migrations/XXXX_add_programs.sql

-- 1. Create PROGRAM_STATUS enum
CREATE TYPE "PROGRAM_STATUS" AS ENUM ('ACTIVE', 'INACTIVE', 'ARCHIVED');

-- 2. Create program table
CREATE TABLE program (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  organization_id UUID NOT NULL REFERENCES organization(id) ON DELETE CASCADE,
  name VARCHAR NOT NULL,
  description TEXT,
  cover_image TEXT,
  status "PROGRAM_STATUS" NOT NULL DEFAULT 'ACTIVE',
  created_by_profile_id UUID REFERENCES profile(id)
);

CREATE INDEX idx_program_organization_id ON program(organization_id);

-- 3. Create program_course join table
CREATE TABLE program_course (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  program_id UUID NOT NULL REFERENCES program(id) ON DELETE CASCADE,
  course_id UUID NOT NULL REFERENCES course(id) ON DELETE CASCADE,
  "order" INTEGER NOT NULL DEFAULT 0,
  added_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE(program_id, course_id)
);

CREATE INDEX idx_program_course_class_id ON program_course(program_id);

-- 4. Create program_member table
CREATE TABLE program_member (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  program_id UUID NOT NULL REFERENCES program(id) ON DELETE CASCADE,
  profile_id UUID REFERENCES profile(id),
  role_id INTEGER NOT NULL REFERENCES role(id),
  email TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE(program_id, profile_id)
);

CREATE INDEX idx_program_member_class_id ON program_member(program_id);
CREATE INDEX idx_program_member_profile_id ON program_member(profile_id);

-- 5. Create program_announcement table
CREATE TABLE program_announcement (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  program_id UUID NOT NULL REFERENCES program(id) ON DELETE CASCADE,
  author_profile_id UUID REFERENCES profile(id),
  title VARCHAR NOT NULL,
  body TEXT,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_program_announcement_class_id ON program_announcement(program_id);

-- 6. Create program_file table
CREATE TABLE program_file (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  program_id UUID NOT NULL REFERENCES program(id) ON DELETE CASCADE,
  uploaded_by_profile_id UUID REFERENCES profile(id),
  name VARCHAR NOT NULL,
  url TEXT NOT NULL,
  mime_type VARCHAR,
  size INTEGER,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX idx_program_file_class_id ON program_file(program_id);

-- 7. Add programId to community_question
ALTER TABLE community_question ADD COLUMN program_id UUID REFERENCES program(id) ON DELETE CASCADE;

Access Control Logic

Two middleware functions are needed in apps/api/src/middleware/:

programAccessMiddleware (read access)

Verifies the caller is either an org admin or a program_member for the given :programId. Used on all GET /program/:programId/* routes.

// apps/api/src/middleware/program-access.ts
export async function programAccessMiddleware(c, next) {
  const { programId } = c.req.param();
  const user = c.get('user')!;
  const isMember = await isProgramMember(programId, user.profileId);
  const isOrgAdmin = await isOrgAdminByProgramId(programId, user.profileId);
  if (!isMember && !isOrgAdmin) throw new AppError('Forbidden', ErrorCodes.FORBIDDEN, 403);
  await next();
}

programAdminMiddleware (write access)

Verifies the caller has roleId 1 (ADMIN) or 2 (TUTOR) within the program, or is an org admin. Used on all mutating routes.

// apps/api/src/middleware/program-admin.ts
export async function programAdminMiddleware(c, next) {
  const { programId } = c.req.param();
  const user = c.get('user')!;
  const role = await getProgramMemberRole(programId, user.profileId);
  const isOrgAdmin = await isOrgAdminByProgramId(programId, user.profileId);
  if (!isOrgAdmin && (!role || role > 2)) throw new AppError('Forbidden', ErrorCodes.FORBIDDEN, 403);
  await next();
}

API and Route Plan

Validation Layer

File: packages/utils/src/validation/program/program.ts

import { z } from 'zod';

export const ZCreateProgram = z.object({
  name: z.string().min(1).max(255),
  description: z.string().max(2000).optional(),
  coverImage: z.string().url().optional()
});
export type TCreateProgram = z.infer<typeof ZCreateProgram>;

export const ZUpdateProgram = z.object({
  name: z.string().min(1).max(255).optional(),
  description: z.string().max(2000).nullable().optional(),
  coverImage: z.string().url().nullable().optional(),
  status: z.enum(['ACTIVE', 'INACTIVE', 'ARCHIVED']).optional()
});
export type TUpdateProgram = z.infer<typeof ZUpdateProgram>;

export const ZAddCourseToProgram = z.object({
  courseId: z.string().uuid(),
  order: z.number().int().min(0).optional()
});
export type TAddCourseToProgram = z.infer<typeof ZAddCourseToProgram>;

export const ZAddProgramMembers = z.object({
  members: z.array(
    z.object({
      email: z.string().email(),
      roleId: z.number().int().min(1).max(3)
    })
  ).min(1)
});
export type TAddProgramMembers = z.infer<typeof ZAddProgramMembers>;

export const ZUpdateProgramMember = z.object({
  roleId: z.number().int().min(1).max(3)
});
export type TUpdateProgramMember = z.infer<typeof ZUpdateProgramMember>;

export const ZCreateProgramAnnouncement = z.object({
  title: z.string().min(1).max(500),
  body: z.string().max(10000).optional()
});
export type TCreateProgramAnnouncement = z.infer<typeof ZCreateProgramAnnouncement>;

export const ZUpdateProgramAnnouncement = z.object({
  title: z.string().min(1).max(500).optional(),
  body: z.string().max(10000).nullable().optional()
});
export type TUpdateProgramAnnouncement = z.infer<typeof ZUpdateProgramAnnouncement>;

export const ZAddProgramFile = z.object({
  name: z.string().min(1).max(255),
  url: z.string().url(),
  mimeType: z.string().optional(),
  size: z.number().int().positive().optional()
});
export type TAddProgramFile = z.infer<typeof ZAddProgramFile>;

Export from: packages/utils/src/validation/program/index.ts and re-export from packages/utils/src/validation/index.ts.

Query Layer

File: packages/db/src/queries/program/program.ts

Function Description
createProgram(data) Insert into program, return created row
getProgramById(programId) Single program with member count and course count
getProgramsByOrg(orgId) All non-archived programs for org, ordered by createdAt desc
updateProgram(programId, data) Update name, description, coverImage, status
getProgramMemberRole(programId, profileId) Return roleId for the given profile in the program, or null
isProgramMember(programId, profileId) Boolean check
isOrgAdminByProgramId(programId, profileId) Joins program → organization → organizationmember to check admin role
addProgramMember(programId, profileId, roleId, email) Insert program_member row (upsert on conflict)
removeProgramMember(programId, memberId) Delete program_member by id
getProgramMembers(programId) All members joined to profile for display
getEnrolledProgramsByProfile(orgId, profileId) All ACTIVE programs where profile is a program member, for LMS
addCourseToProgram(programId, courseId, order) Insert program_course row
removeCourseFromProgram(programId, courseId) Delete program_course row
getCoursesByProgram(programId) All courses in program ordered by order, joined to course
getStudentMemberIdsByProgram(programId) All profileId values with roleId = 3 in program (for auto-enrollment)
createProgramAnnouncement(data) Insert program_announcement
getProgramAnnouncements(programId) All announcements ordered by createdAt desc, joined to profile
updateProgramAnnouncement(announcementId, data) Update title/body
deleteProgramAnnouncement(announcementId) Delete row
addProgramFile(data) Insert program_file
getProgramFiles(programId) All files ordered by createdAt desc
deleteProgramFile(fileId) Delete program_file by id

Export from: packages/db/src/queries/program/index.ts

Service Layer

File: apps/api/src/services/program/program.ts

createProgram(orgId, profileId, data: TCreateProgram)

  • Insert program row.
  • Add creator as program_member with roleId = 1 (ADMIN).
  • Return the new program.

addCourseToProgram(programId, courseId)

  • Verify program exists and course belongs to the same org.
  • Insert program_course row (error if already linked).
  • Fetch all current STUDENT program members (getStudentMemberIdsByProgram).
  • For each student profile, look up their groupmember status in the course's group; if not already enrolled, call enrollInCourse (or insert groupmember directly if the course is free and no invite is needed).
  • All writes in a single transaction.
  • Return updated course list for the program.

removeCourseFromProgram(programId, courseId)

  • Delete program_course row.
  • No changes to groupmember records.
  • Return updated course list.

addMembersToProgram(programId, members: TAddProgramMembers['members'])

Transaction:

  1. For each member in the batch, resolve profileId from email (look up profile by email, create if none exists as an invited-but-unregistered user following the same pattern as addGroupMember).
  2. Insert program_member row (skip if already a member of the program).
  3. If roleId = 3 (STUDENT), fetch all courses in the program (getCoursesByProgram). For each course, check if the student is already a groupmember; if not, insert a groupmember row with roleId = 3.

removeMemberFromProgram(programId, memberId)

  • Delete program_member row by id.
  • Leave all groupmember rows in individual courses intact.

createAnnouncement(programId, profileId, data: TCreateProgramAnnouncement)

  • Verify caller is program admin or tutor.
  • Insert program_announcement row.
  • Return new announcement.

addFile(programId, profileId, data: TAddProgramFile)

  • Insert program_file row.
  • Return new file record.

deleteFile(fileId, profileId)

  • Verify caller is program admin or tutor.
  • Delete program_file row.

Route Layer

File: apps/api/src/routes/program/program.ts

All routes require authMiddleware. Routes scoped to a :programId also apply programAccessMiddleware (read) or programAdminMiddleware (write) as noted.

Method Path Middleware Description
GET /program authMiddleware List org's programs (org admin sees all; tutors/students see their own)
POST /program authMiddleware + orgAdmin Create program
GET /program/:programId programAccessMiddleware Get program with member/course counts
PUT /program/:programId programAdminMiddleware Update program name, description, cover, status
DELETE /program/:programId orgAdmin Archive program (status = 'ARCHIVED')
GET /program/:programId/courses programAccessMiddleware List courses in program (ordered)
POST /program/:programId/courses programAdminMiddleware Add course to program + auto-enroll students
DELETE /program/:programId/courses/:courseId programAdminMiddleware Remove course from program
GET /program/:programId/members programAdminMiddleware List program members with profile info
POST /program/:programId/members programAdminMiddleware Batch-add members + auto-enroll students
PUT /program/:programId/members/:memberId programAdminMiddleware Update member role
DELETE /program/:programId/members/:memberId programAdminMiddleware Remove member from program
GET /program/:programId/announcements programAccessMiddleware List announcements
POST /program/:programId/announcements programAdminMiddleware Create announcement
PUT /program/:programId/announcements/:announcementId programAdminMiddleware Update announcement
DELETE /program/:programId/announcements/:announcementId programAdminMiddleware Delete announcement
GET /program/:programId/files programAccessMiddleware List files
POST /program/:programId/files programAdminMiddleware Add file record
DELETE /program/:programId/files/:fileId programAdminMiddleware Delete file

Route Registration

// apps/api/src/routes/program/index.ts
export * from './program';

// apps/api/src/app.ts
import { classRouter } from '@api/routes/program';
export const app = new Hono()
  // ... existing routes ...
  .route('/program', classRouter);

LMS Enrolled Programs Route

Add to apps/api/src/routes/organization/organization.ts:

GET /organization/programs/enrolled

Returns all ACTIVE programs where the current user is a STUDENT program_member, including the course list with per-course progress. Used by the LMS "My Programs" and "Program Hub" pages.

Build Verification

pnpm --filter @cio/utils build
pnpm --filter @cio/db build
pnpm --filter @cio/api build

Frontend Plan (Dashboard)

Request Types

File: apps/dashboard/src/lib/features/program/utils/types.ts

import { classroomio, type InferResponseType } from '$lib/utils/services/api';

export type ListClassesRequest = typeof classroomio.program.$get;
export type CreateClassRequest = typeof classroomio.program.$post;
export type GetClassRequest = typeof classroomio.program[':programId']['$get'];
export type UpdateClassRequest = typeof classroomio.program[':programId']['$put'];
export type ListProgramCoursesRequest = typeof classroomio.program[':programId']['courses']['$get'];
export type AddCourseToClassRequest = typeof classroomio.program[':programId']['courses']['$post'];
export type ListProgramMembersRequest = typeof classroomio.program[':programId']['members']['$get'];
export type AddProgramMembersRequest = typeof classroomio.program[':programId']['members']['$post'];
export type ListAnnouncementsRequest = typeof classroomio.program[':programId']['announcements']['$get'];
export type CreateAnnouncementRequest = typeof classroomio.program[':programId']['announcements']['$post'];
export type ListProgramFilesRequest = typeof classroomio.program[':programId']['files']['$get'];

export type ListClassesSuccess = Extract<InferResponseType<ListClassesRequest>, { success: true }>;
export type ProgramItem = ListClassesSuccess['data'][number];

export type GetClassSuccess = Extract<InferResponseType<GetClassRequest>, { success: true }>;
export type ProgramDetail = GetClassSuccess['data'];

export type ListProgramCoursesSuccess = Extract<InferResponseType<ListProgramCoursesRequest>, { success: true }>;
export type ProgramCourse = ListProgramCoursesSuccess['data'][number];

export type ListProgramMembersSuccess = Extract<InferResponseType<ListProgramMembersRequest>, { success: true }>;
export type ProgramMember = ListProgramMembersSuccess['data'][number];

export type ListAnnouncementsSuccess = Extract<InferResponseType<ListAnnouncementsRequest>, { success: true }>;
export type ProgramAnnouncement = ListAnnouncementsSuccess['data'][number];

export type ListProgramFilesSuccess = Extract<InferResponseType<ListProgramFilesRequest>, { success: true }>;
export type ProgramFile = ListProgramFilesSuccess['data'][number];

// LMS enrolled programs
export type EnrolledClassesRequest = typeof classroomio.organization.programs.enrolled['$get'];
export type EnrolledClassesSuccess = Extract<InferResponseType<EnrolledClassesRequest>, { success: true }>;
export type EnrolledClass = EnrolledClassesSuccess['data'][number];

API Program

File: apps/dashboard/src/lib/features/program/api/program.svelte.ts

program ProgramApi extends BaseApiWithErrors {
  programs = $state<ProgramItem[]>([]);
  currentClass = $state<ProgramDetail | null>(null);
  courses = $state<ProgramCourse[]>([]);
  members = $state<ProgramMember[]>([]);
  announcements = $state<ProgramAnnouncement[]>([]);
  files = $state<ProgramFile[]>([]);
  loading = $state(false);

  async list() { /* GET /program */ }
  async get(programId: string) { /* GET /program/:programId */ }
  async create(data: TCreateProgram) { /* POST /program */ }
  async update(programId: string, data: TUpdateProgram) { /* PUT /program/:programId */ }
  async archive(programId: string) { /* DELETE /program/:programId */ }

  async listCourses(programId: string) { /* GET /program/:programId/courses */ }
  async addCourse(programId: string, data: TAddCourseToProgram) { /* POST /program/:programId/courses */ }
  async removeCourse(programId: string, courseId: string) { /* DELETE /program/:programId/courses/:courseId */ }

  async listMembers(programId: string) { /* GET /program/:programId/members */ }
  async addMembers(programId: string, data: TAddProgramMembers) { /* POST /program/:programId/members */ }
  async removeMember(programId: string, memberId: string) { /* DELETE /program/:programId/members/:memberId */ }

  async listAnnouncements(programId: string) { /* GET /program/:programId/announcements */ }
  async createAnnouncement(programId: string, data: TCreateProgramAnnouncement) { /* POST */ }
  async deleteAnnouncement(programId: string, announcementId: string) { /* DELETE */ }

  async listFiles(programId: string) { /* GET /program/:programId/files */ }
  async addFile(programId: string, data: TAddProgramFile) { /* POST /program/:programId/files */ }
  async deleteFile(programId: string, fileId: string) { /* DELETE /program/:programId/files/:fileId */ }
}

export const programApi = new ProgramApi();

LMS API Program

File: apps/dashboard/src/lib/features/lms/api/program.svelte.ts

program LmsProgramApi extends BaseApiWithErrors {
  enrolledClasses = $state<EnrolledClass[]>([]);
  loading = $state(false);

  async listEnrolled() { /* GET /organization/programs/enrolled */ }
}

export const lmsProgramApi = new LmsProgramApi();

Admin Pages

Route File Purpose
/courses/programs apps/dashboard/src/routes/courses/programs/+page.svelte List all org programs
/courses/programs/new apps/dashboard/src/routes/courses/programs/new/+page.svelte Create program form
/courses/programs/[programId] apps/dashboard/src/routes/courses/programs/[programId]/+page.svelte Program overview
/courses/programs/[programId]/courses .../courses/+page.svelte Manage courses
/courses/programs/[programId]/people .../people/+page.svelte Manage members
/courses/programs/[programId]/announcements .../announcements/+page.svelte Manage announcements
/courses/programs/[programId]/files .../files/+page.svelte File library management

Feature pages live in: apps/dashboard/src/lib/features/program/pages/

LMS Pages

Route File Purpose
/lms/programs apps/dashboard/src/routes/lms/programs/+page.svelte My enrolled programs
/lms/programs/[programId] apps/dashboard/src/routes/lms/programs/[programId]/+page.svelte Program hub (courses + announcements + files)
/lms/programs/[programId]/community .../community/+page.svelte Program community Q&A

Feature pages live in: apps/dashboard/src/lib/features/lms/pages/program/

Navigation Updates

Org admin sidebar (apps/dashboard/src/lib/features/org/):

  • Add "Programs" nav item at the same level as "Courses", linking to /courses/programs.
  • Use a suitable icon (e.g., a group/layers icon).

LMS sidebar (apps/dashboard/src/lib/features/lms/):

  • Add "Programs" nav item (shown conditionally: only when enrolledClasses.length > 0).
  • Position between "My Learning" and "Exercises".

Translations

File: apps/dashboard/src/lib/utils/translations/en.json

Add keys under program:

{
  "program": {
    "title": "Programs",
    "my_classes": "My Programs",
    "create": "Create Program",
    "create_description": "Group multiple courses and materials under one program for your students.",
    "name": "Program Name",
    "description": "Description",
    "cover_image": "Cover Image",
    "status": "Status",
    "active": "Active",
    "inactive": "Inactive",
    "archived": "Archived",
    "courses": "Courses",
    "people": "People",
    "announcements": "Announcements",
    "files": "Files",
    "community": "Community",
    "add_course": "Add Course",
    "remove_course": "Remove Course",
    "add_members": "Add Members",
    "remove_member": "Remove Member",
    "course_count": "{count} courses",
    "student_count": "{count} students",
    "new_announcement": "New Announcement",
    "announcement_title": "Announcement Title",
    "announcement_body": "Write your announcement...",
    "upload_file": "Upload File",
    "no_classes": "No programs yet. Create one to get started.",
    "no_courses": "No courses in this program yet.",
    "no_members": "No members yet. Add students or tutors.",
    "no_announcements": "No announcements yet.",
    "no_files": "No files uploaded yet.",
    "archive_confirm": "Archiving this program will hide it from all views. Are you sure?",
    "auto_enroll_note": "Adding this course will enroll all current program students in it.",
    "remove_course_note": "Removing this course will not unenroll any students.",
    "remove_member_note": "Removing this member will not unenroll them from individual courses."
  }
}

Frontend Build Verification

pnpm --filter @cio/dashboard build

Implementation Order

Phase 1: Database + Schema

  1. Add programStatus enum to packages/db/src/schema.ts.
  2. Add lmsProgram, programCourse, programMember, programAnnouncement, programFile tables to schema.
  3. Add programId FK column to communityQuestion table in schema.
  4. Write and apply migration SQL: packages/db/src/migrations/XXXX_add_programs.sql.
  5. Run pnpm --filter @cio/db build.

Phase 2: Validation + Queries

  1. Create packages/utils/src/validation/program/program.ts with all Zod schemas.
  2. Export from packages/utils/src/validation/program/index.ts and re-export from packages/utils/src/validation/index.ts.
  3. Run pnpm --filter @cio/utils build.
  4. Create packages/db/src/queries/program/program.ts with all query functions.
  5. Create packages/db/src/queries/program/index.ts and export.
  6. Run pnpm --filter @cio/db build.

Phase 3: Service + Routes

  1. Create apps/api/src/services/program/program.ts with all service functions (auto-enrollment transactions are the most complex part).
  2. Create access control utilities: apps/api/src/middleware/program-access.ts and apps/api/src/middleware/program-admin.ts.
  3. Add new error codes to apps/api/src/utils/errors.ts: PROGRAM_NOT_FOUND, PROGRAM_FORBIDDEN, COURSE_ALREADY_IN_PROGRAM, MEMBER_ALREADY_IN_PROGRAM.
  4. Create apps/api/src/routes/program/program.ts with all route handlers.
  5. Create apps/api/src/routes/program/index.ts and register in apps/api/src/app.ts.
  6. Add GET /organization/programs/enrolled to the organization router.
  7. Run pnpm --filter @cio/api build.

Phase 4: Admin Frontend

  1. Add request/response types to apps/dashboard/src/lib/features/program/utils/types.ts.
  2. Create apps/dashboard/src/lib/features/program/api/program.svelte.ts API program.
  3. Add translation keys to en.json.
  4. Create admin feature pages under apps/dashboard/src/lib/features/program/pages/.
  5. Create SvelteKit route files under apps/dashboard/src/routes/courses/programs/.
  6. Add "Programs" nav item to the org admin sidebar.
  7. Run pnpm --filter @cio/dashboard build.

Phase 5: LMS Frontend

  1. Create apps/dashboard/src/lib/features/lms/api/program.svelte.ts.
  2. Create LMS feature pages under apps/dashboard/src/lib/features/lms/pages/program/.
  3. Create SvelteKit route files under apps/dashboard/src/routes/lms/programs/.
  4. Add "Programs" nav item to the LMS sidebar (conditional on having enrolled programs).
  5. Run pnpm --filter @cio/dashboard build.

Acceptance Criteria

  1. Org admin can create a program, add courses to it, and add students — all from the admin dashboard.
  2. When a student is added to a program, groupmember rows are automatically created for every course in the program.
  3. When a course is added to an existing program that already has students, all those students are enrolled in the new course.
  4. Removing a student from a program does not remove their groupmember records in individual courses.
  5. Removing a course from a program does not unenroll any students.
  6. Students see a "Programs" section in the LMS sidebar (only when enrolled in at least one program).
  7. The program hub page shows all courses with per-course progress bars, the announcements feed, and the file library.
  8. Program admins and tutors can post announcements and upload files; students can only view them.
  9. Program community Q&A is scoped to the program and does not appear on course community boards.
  10. INACTIVE programs are hidden from the student LMS but remain fully accessible to admins and tutors.
  11. ARCHIVED programs are hidden from all views.
  12. Courses that are not in any program, and courses whose students were enrolled independently, continue to work exactly as they do today (zero regression on existing groupmember and course data).
  13. All user-facing strings use translation keys (no hardcoded English).
  14. pnpm --filter @cio/api build and pnpm --filter @cio/dashboard build pass after implementation.

Risks and Mitigations

  • Risk: Auto-enrollment transaction for large programs (hundreds of students, tens of courses) times out or partially fails.

    • Mitigation: Process auto-enrollment in the service layer using a single transaction with batch inserts (insert multiple groupmember rows in one query using Drizzle's batch insert). For very large programs (> 500 students), offload to a background job via the existing email job queue or a new async task runner, and return a 202 Accepted with a polling endpoint.

  • Risk: A student is already enrolled in a course independently before being added to a program. Duplicate groupmember rows violate the (groupId, profileId) unique constraint.

    • Mitigation: The enrollment logic in addMembersToProgram must check for existing membership before inserting. Use INSERT ... ON CONFLICT DO NOTHING or check with isUserCourseMember before inserting. This is already idempotent in the existing enrollment service.

  • Risk: The community_question.programId column causes existing community queries to break if they don't filter by programId IS NULL for course-scoped questions.

    • Mitigation: Add programId IS NULL to all existing community query filters where courseId is used. The column is nullable so existing rows default to NULL and behavior is unchanged. Update packages/db/src/queries/community/community.ts alongside the schema migration.

  • Risk: Removing a course from a program causes confusion: students are still enrolled in the course but it no longer appears in the program hub.

    • Mitigation: Show a confirmation dialog in the admin UI with the note: "Removing this course will not unenroll any students. They will still have access to it via My Learning." Use the program.remove_course_note translation key already specified.

  • Risk: Org nav gets crowded with a new "Programs" top-level item.

    • Mitigation: Place "Programs" directly below "Courses" in the sidebar. Consider grouping them under a "Learning" section header if more items are added in future.
Reference in New Issue View Git Blame Copy Permalink