classroomio/prd/course-templates

Course Templates PRD

Purpose

Enable instructors to create reusable course blueprints (templates) that can be used to quickly spin up new courses with pre-built structure, content, and settings. Templates reduce repetitive setup work and help organizations standardize course quality.

Problem Statement

Currently, the only way to reuse course content in ClassroomIO is the clone feature, which creates a full copy of a specific course. This has limitations:

• No discoverability: There is no way to browse reusable starting points when creating a course. Instructors must know which existing course to clone.
• No separation of blueprint vs live course: Cloned courses immediately become live courses with active status, mixing templates with real courses in the listing.
• No selective content inclusion: Clone copies everything — there is no way to include structure but exclude detailed content, or include exercises but exclude lesson notes.
• No organizational template library: Organizations cannot curate a set of approved course structures for their instructors to use.
• isTemplate field is unused: The course table already has an isTemplate boolean (defaults to true), but it is never meaningfully filtered on — every course has it set to true.

Confirmed Decisions

1. Templates are courses: A template is a course row with isTemplate = true and status = 'TEMPLATE'. No new content tables are needed. The existing course editor is reused for building templates.
2. Org-scoped: Templates belong to an organization (via the existing group → organizationId relationship). Each org has its own template library.
3. Built on clone infrastructure: Creating a course from a template reuses the existing cloneCourse() service with modifications to mark the result as a real course (isTemplate = false).
4. Templates are never published: Templates do not appear in public course listings, student-facing pages, or enrollment flows. They are instructor-only blueprints.
5. Non-destructive: Deleting a template does not affect courses already created from it. Courses created from a template become fully independent copies.
6. Selective content: When saving an existing course as a template, instructors can choose which content types to include (structure, lesson content, exercises, settings).

Current-State Audit

Capability	Current State	Notes
isTemplate field	Exists on course table, defaults to true	Never filtered on — effectively unused
Course cloning	Full deep-copy via cloneCourse() service	Copies sections, lessons, exercises, questions, options, translations
Clone UI	"Clone" option in course card dropdown menu	Component: copy-course-modal.svelte
Clone endpoint	POST /course/:courseId/clone	Accepts title, description, slug, organizationId
Course creation	Two-step modal: type selection → title/description	Component: new-course-modal.svelte
Exercise templates	Separate exercise_template table	Existing pattern for template-based creation at exercise level
Course listing filter	Queries getOrgCourses() with filters for title, tags, sort	No filter for isTemplate or status = 'TEMPLATE'
Course status	Text field, default 'ACTIVE'	Used for soft delete ('DELETED'), no 'TEMPLATE' value

Data Sources Checked

• packages/db/src/schema.ts — course table definition, isTemplate field
• apps/api/src/services/course/clone.ts — full clone implementation
• apps/api/src/services/course/course.ts — course creation flow
• apps/api/src/routes/course/course.ts — course routes including clone
• apps/dashboard/src/lib/features/course/components/new-course-modal.svelte — creation UI
• apps/dashboard/src/lib/features/course/components/copy-course-modal.svelte — clone UI
• apps/dashboard/src/lib/features/course/api/course.svelte.ts — frontend course API
• apps/dashboard/src/lib/features/course/api/course-clone.svelte.ts — frontend clone API
• apps/dashboard/src/routes/org/[slug]/courses/+page.svelte — course listing page
• packages/db/src/queries/course/course.ts — course queries
• apps/dashboard/src/lib/features/ui/navigation/org-navigation.ts — org navigation

Product Goals

1. Instructors can save any existing course as a reusable template with selective content inclusion.
2. Instructors can create templates from scratch using the existing course editor.
3. When creating a new course, instructors can choose to start from a template instead of a blank course.
4. Organizations have a template library (tab on the courses page) where templates are managed.
5. Templates are cleanly separated from live courses in all listings and queries.
6. Courses created from templates are fully independent — no ongoing link or sync.
7. The existing course creation and clone flows remain unchanged for users who do not use templates.

Non-Goals (v1)

• Platform-wide template marketplace (orgs sharing templates publicly).
• ClassroomIO-provided starter templates (curated by the platform team).
• AI-generated templates (e.g., "Generate a template for a 4-week React course").
• Template versioning or change tracking.
• Syncing updates from a template to courses already created from it.
• Template access control (e.g., restricting which instructors can use which templates).
• Template analytics beyond usage count.

UX Flow

Flow 1: Creating a Template from an Existing Course

Entry points:

• Course card dropdown menu → "Save as Template" (alongside existing "Clone" option)
• Course Settings page → "Save as Template" button

Steps:

1. User clicks "Save as Template."
2. A modal appears with:
   • Template name — pre-filled with "{course title} Template", editable.
   • Description — pre-filled from course description, editable.
   • Category — optional free-text or select from existing categories (e.g., "Onboarding", "Compliance", "Technical").
   • What to include — checkboxes:
     • Sections & structure (always on, disabled)
     • Lesson content (notes, videos, documents) — default on
     • Exercises & quizzes — default on
     • Course settings (grading, certificates, metadata) — default on
     • Landing page content — default off
   • Info note: "Student data, submissions, and enrollments are never included."
3. User confirms → system clones the course into a new course row with isTemplate = true, status = 'TEMPLATE', isPublished = false.
4. Success snackbar: "Template created" with a link to the templates tab.

Flow 2: Creating a Template from Scratch

Entry point: Templates tab on the courses page → "Create Template" button.

Steps:

1. User clicks "Create Template."
2. Same two-step modal as course creation (type selection → title/description), but the resulting course is marked as a template.
3. Navigates to the course editor with a "Template" badge in the header.
4. User builds out the structure (sections, lessons, exercises) using the existing editor.
5. Template never appears in student-facing listings.

Flow 3: Creating a Course from a Template

Entry point: Existing "Create Course" button on the courses page.

Steps:

1. User clicks "Create Course."
2. Step 1 — Choose starting point (replaces the current type selection step):
   • Two cards: "Blank Course" and "From Template".
   • "Blank Course" proceeds to the existing flow (type → title/description).
   • "From Template" opens the template picker (step 1b).
3. Step 1b — Template picker:
   • Search bar to filter templates by name.
   • Category filter tabs (if categories exist).
   • Grid of template cards showing: name, description snippet, lesson count, exercise count, course type badge.
   • Each card has a "Preview" action that expands a panel showing the full section/lesson outline (read-only).
   • User selects a template and clicks "Use Template."
4. Step 2 — Customize:
   • Title — pre-filled from template, editable.
   • Description — pre-filled from template, editable.
   • Type — inherited from template, overridable (Live Class / Self-paced).
   • Subtitle: "Based on: {template name}".
5. User clicks "Create Course" → system clones the template into a real course (isTemplate = false, status = 'ACTIVE') → navigates to the new course editor with all template content pre-populated.

Flow 4: Managing Templates

Entry point: Courses page → "Templates" tab.

The courses page (/org/[slug]/courses) gets a tab bar: [My Courses] | [Templates].

Templates tab features:

• Grid of template cards with: name, description, course type, lesson count, exercise count, usage count ("Used N times").
• Card dropdown menu: Edit, Duplicate, Delete.
• "Create Template" button.
• Edit: Opens the course editor with a "Template" badge. Same editing experience as a real course.
• Duplicate: Clones the template into another template.
• Delete: Soft-deletes the template (status = 'DELETED'). Confirmation dialog: "This will not affect courses already created from this template."

Technical Design

Data Model Changes

Modified Table: course

1. Fix isTemplate default from true to false. New courses should not be flagged as templates by default.
2. Add templateSourceId — nullable UUID FK to course.id. Tracks which template a course was created from. Used for usage count analytics ("12 courses created from this template").
3. Add templateCategory — nullable varchar. Optional category for organizing templates in the picker.

// packages/db/src/schema.ts — additions to course table

isTemplate: boolean('is_template').default(false),  // changed from true to false
templateSourceId: uuid('template_source_id'),
templateCategory: varchar('template_category'),

// Add to constraints:
foreignKey({
  columns: [table.templateSourceId],
  foreignColumns: [table.id],
  name: 'course_template_source_id_fkey'
}).onDelete('set null')

No new tables needed. Templates are courses filtered by isTemplate = true and status = 'TEMPLATE'.

Backward Compatibility

Existing courses all have isTemplate = true due to the current default. A data migration will set isTemplate = false for all existing courses (they are real courses, not templates). The migration is safe because the field is not currently used in any queries or business logic.

Migration

Create migration file: packages/db/src/migrations/XXXX_add_course_templates.sql

-- 1. Fix isTemplate for all existing courses (they are real courses, not templates)
UPDATE course SET is_template = false WHERE is_template = true;

-- 2. Change default for is_template to false
ALTER TABLE course ALTER COLUMN is_template SET DEFAULT false;

-- 3. Add template_source_id column
ALTER TABLE course ADD COLUMN template_source_id UUID REFERENCES course(id) ON DELETE SET NULL;

-- 4. Add template_category column
ALTER TABLE course ADD COLUMN template_category VARCHAR(255);

-- 5. Add index for template queries
CREATE INDEX idx_course_is_template ON course(is_template) WHERE is_template = true;

-- 6. Add index for template usage count
CREATE INDEX idx_course_template_source_id ON course(template_source_id) WHERE template_source_id IS NOT NULL;

Validation Layer

File: packages/utils/src/validation/course/template.ts

import { z } from 'zod';

export const ZSaveAsTemplate = z.object({
  title: z.string().min(1).max(255),
  description: z.string().min(1),
  category: z.string().max(100).optional(),
  includeLessonContent: z.boolean().default(true),
  includeExercises: z.boolean().default(true),
  includeSettings: z.boolean().default(true),
  includeLandingPage: z.boolean().default(false)
});

export type TSaveAsTemplate = z.infer<typeof ZSaveAsTemplate>;

export const ZCreateFromTemplate = z.object({
  templateId: z.string().uuid(),
  title: z.string().min(1),
  description: z.string().min(1),
  type: z.enum(['LIVE_CLASS', 'SELF_PACED']).optional(),
  organizationId: z.string().min(1)
});

export type TCreateFromTemplate = z.infer<typeof ZCreateFromTemplate>;

export const ZCreateTemplate = z.object({
  title: z.string().min(1),
  description: z.string().min(1),
  type: z.enum(['LIVE_CLASS', 'SELF_PACED']),
  category: z.string().max(100).optional(),
  organizationId: z.string().min(1)
});

export type TCreateTemplate = z.infer<typeof ZCreateTemplate>;

export const ZUpdateTemplate = z.object({
  title: z.string().min(1).max(255).optional(),
  description: z.string().min(1).optional(),
  category: z.string().max(100).nullable().optional()
});

export type TUpdateTemplate = z.infer<typeof ZUpdateTemplate>;

Export from: packages/utils/src/validation/course/index.ts

Query Layer

File: packages/db/src/queries/course/template.ts

Functions:

• getOrgTemplates(organizationId) — list all templates for an org. Returns templates with lesson count, exercise count, and usage count (number of courses with templateSourceId pointing to this template). Ordered by createdAt desc.
• getTemplateById(templateId) — single template with full details and usage count.
• getTemplateUsageCount(templateId) — count of courses created from this template.

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

Service Layer

File: apps/api/src/services/course/template.ts

saveAsTemplate(courseId, userId, data: TSaveAsTemplate)

• Fetch the source course.
• Clone it via a modified cloneCourse() that respects the include* flags:
  • Always clone sections (structure).
  • Skip lesson content (notes, videos, documents) if includeLessonContent = false — create lessons with title and order only.
  • Skip exercises if includeExercises = false.
  • Skip metadata fields if includeSettings = false.
  • Skip landing page fields (bannerImage, metadata.videoUrl, etc.) if includeLandingPage = false.
• Set isTemplate = true, status = 'TEMPLATE', isPublished = false on the new course.
• Set templateCategory if provided.
• Return the new template.

createTemplate(userId, data: TCreateTemplate)

• Create a new course with isTemplate = true, status = 'TEMPLATE', isPublished = false.
• Follow the same transaction as createCourse() (create group → course → add creator as TUTOR).
• Set templateCategory if provided.
• Return the new template.

createFromTemplate(templateId, userId, data: TCreateFromTemplate)

• Fetch the template. Verify isTemplate = true.
• Clone via cloneCourse() with all content included.
• Override: isTemplate = false, status = 'ACTIVE', isPublished = false.
• Override: title, description, type from user input.
• Set templateSourceId = templateId on the new course.
• Return the new course.

deleteTemplate(templateId)

• Verify the course is a template (isTemplate = true).
• Soft delete: set status = 'DELETED'.
• Does not affect courses with templateSourceId = templateId.

Route Layer

File: apps/api/src/routes/course/template.ts

All routes nested under /course/template and require authMiddleware + admin/tutor role.

Method	Path	Description
GET	/course/template	List org templates (query param: organizationId)
POST	/course/template	Create blank template
GET	/course/template/:templateId	Get template details
PUT	/course/template/:templateId	Update template metadata
DELETE	/course/template/:templateId	Soft-delete template
POST	/course/:courseId/save-as-template	Save existing course as template
POST	/course/template/:templateId/create-course	Create new course from template
POST	/course/template/:templateId/duplicate	Duplicate a template

Route Registration

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

// Registration in course router
.route('/template', templateRouter)

Modified Existing Queries

getOrgCourses(organizationId, ...)

Add filter: WHERE is_template = false AND status != 'TEMPLATE' to exclude templates from the normal course listing. This ensures the "My Courses" tab only shows real courses.

Error Codes

Add to apps/api/src/utils/errors.ts:

TEMPLATE_NOT_FOUND: 'TEMPLATE_NOT_FOUND',
NOT_A_TEMPLATE: 'NOT_A_TEMPLATE',

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/course/utils/types.ts

export type ListTemplatesRequest = typeof classroomio.course.template.$get;
export type CreateTemplateRequest = typeof classroomio.course.template.$post;
export type GetTemplateRequest = typeof classroomio.course.template[':templateId']['$get'];
export type UpdateTemplateRequest = typeof classroomio.course.template[':templateId']['$put'];
export type DeleteTemplateRequest = typeof classroomio.course.template[':templateId']['$delete'];
export type SaveAsTemplateRequest = typeof classroomio.course[':courseId']['save-as-template']['$post'];
export type CreateFromTemplateRequest = typeof classroomio.course.template[':templateId']['create-course']['$post'];

export type ListTemplatesSuccess = Extract<InferResponseType<ListTemplatesRequest>, { success: true }>;
export type CourseTemplate = ListTemplatesSuccess['data'][number];

API Class

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

class TemplateApi extends BaseApiWithErrors {
  templates = $state<CourseTemplate[]>([]);
  loading = $state(false);

  async list(organizationId: string) { ... }
  async create(data: TCreateTemplate) { ... }
  async update(templateId: string, data: TUpdateTemplate) { ... }
  async remove(templateId: string) { ... }
  async saveAsTemplate(courseId: string, data: TSaveAsTemplate) { ... }
  async createFromTemplate(templateId: string, data: TCreateFromTemplate) { ... }
  async duplicate(templateId: string) { ... }
}

New/Modified Components

save-as-template-modal.svelte

Location: apps/dashboard/src/lib/features/course/components/save-as-template-modal.svelte

Modal with: title, description, category, content inclusion checkboxes, confirm button.

template-picker.svelte

Location: apps/dashboard/src/lib/features/course/components/template-picker.svelte

Grid of template cards with search, category filters, preview panel, and "Use Template" action.

Modified: new-course-modal.svelte

Add a new initial step: "Blank Course" vs "From Template" card selection. "Blank" proceeds to existing flow. "From Template" shows template-picker.svelte, then proceeds to the customize step.

Modified: Course card dropdown

Add "Save as Template" option alongside existing "Clone" option.

Modified: Courses page

Add tab bar: [My Courses] | [Templates]. The templates tab renders the template management grid.

Template Badge

When editing a template in the course editor, show a persistent badge in the header: a colored pill reading "Template" (e.g., bg-blue-100 text-blue-800). This makes it clear the user is editing a blueprint, not a live course.

Routes

Route	Page
/org/[slug]/courses?tab=templates	Templates tab on courses page (no new route file — tab state via query param)

No new route files needed — the templates tab lives on the existing courses page, controlled by a tab query parameter.

Translations

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

Add keys under course.templates:

{
  "course": {
    "templates": {
      "title": "Templates",
      "create": "Create Template",
      "save_as_template": "Save as Template",
      "from_template": "From Template",
      "blank_course": "Blank Course",
      "blank_course_description": "Start with an empty course",
      "from_template_description": "Choose from your template library",
      "choose_starting_point": "How would you like to start?",
      "choose_template": "Choose a template",
      "customize_course": "Customize your course",
      "based_on": "Based on: {name}",
      "use_template": "Use Template",
      "preview": "Preview",
      "template_name": "Template Name",
      "category": "Category",
      "what_to_include": "What to include",
      "sections_structure": "Sections & structure",
      "lesson_content": "Lesson content (notes, videos, documents)",
      "exercises_quizzes": "Exercises & quizzes",
      "course_settings": "Course settings (grading, certificates)",
      "landing_page_content": "Landing page content",
      "student_data_note": "Student data, submissions, and enrollments are never included.",
      "template_created": "Template created",
      "view_templates": "View in Templates",
      "template_badge": "Template",
      "used_times": "Used {count} times",
      "no_templates": "No templates yet. Save an existing course as a template or create one from scratch.",
      "delete_confirm": "This will not affect courses already created from this template.",
      "lessons_count": "{count} lessons",
      "exercises_count": "{count} exercises",
      "search_templates": "Search templates..."
    }
  }
}

Frontend Build Verification

pnpm --filter @cio/dashboard build

Implementation Order

Phase 1: Database + Schema

1. Update isTemplate default from true to false in schema.
2. Add templateSourceId and templateCategory columns to course table in schema.
3. Create migration: fix existing data, add columns, add indexes.
4. Run pnpm --filter @cio/db build.

Phase 2: Validation + Queries

1. Create packages/utils/src/validation/course/template.ts with all Zod schemas.
2. Export from packages/utils/src/validation/course/index.ts.
3. Create packages/db/src/queries/course/template.ts with query functions.
4. Update getOrgCourses to exclude templates.
5. Export from packages/db/src/queries/course/index.ts.
6. Run pnpm --filter @cio/utils build and pnpm --filter @cio/db build.

Phase 3: Service + Routes

1. Create apps/api/src/services/course/template.ts with all service functions.
2. Refactor cloneCourse() to accept an options object for selective content cloning.
3. Create apps/api/src/routes/course/template.ts with all route handlers.
4. Register template router in course route index.
5. Add error codes to apps/api/src/utils/errors.ts.
6. Run pnpm --filter @cio/api build.

Phase 4: Frontend — Template Management

1. Add request types to apps/dashboard/src/lib/features/course/utils/types.ts.
2. Create apps/dashboard/src/lib/features/course/api/template.svelte.ts API class.
3. Add translation keys to en.json.
4. Add "Templates" tab to courses page.
5. Create template card component for the grid.
6. Add "Save as Template" to course card dropdown and course settings.
7. Create save-as-template-modal.svelte.
8. Run pnpm --filter @cio/dashboard build.

Phase 5: Frontend — Create from Template

1. Modify new-course-modal.svelte to add "Blank" vs "From Template" step.
2. Create template-picker.svelte with search, categories, preview.
3. Add customize step with template-prefilled fields.
4. Add "Template" badge to course editor header when editing a template.
5. Run pnpm --filter @cio/dashboard build.

Acceptance Criteria

1. Instructor can save an existing course as a template with selective content inclusion.
2. Instructor can create a blank template from the templates tab.
3. Templates appear in the "Templates" tab and do not appear in the "My Courses" tab.
4. Instructor can create a new course from a template via the "Create Course" flow.
5. Courses created from templates are fully independent — editing the template does not affect the course and vice versa.
6. Template cards show lesson count, exercise count, and usage count.
7. Template picker supports search and category filtering.
8. Template preview shows the section/lesson outline in a read-only view.
9. Existing course creation flow ("Blank Course") is unchanged.
10. Existing clone functionality is unchanged.
11. Deleting a template does not affect courses created from it.
12. Templates are not visible to students in any listing or enrollment flow.
13. Editing a template uses the same course editor with a "Template" badge.
14. All existing courses have isTemplate = false after migration.
15. All new UI strings use translation keys (no hardcoded English).
16. pnpm --filter @cio/api build and pnpm --filter @cio/dashboard build pass after implementation.

Risks and Mitigations

• Risk: Changing isTemplate default from true to false and bulk-updating existing courses could cause issues if any code relies on isTemplate = true.

  • Mitigation: Codebase search confirms isTemplate is never used in filtering or conditional logic — it is only copied during clone. The migration is safe.

• Risk: Refactoring cloneCourse() to support selective content could break existing clone functionality.

  • Mitigation: The refactor adds an optional options parameter. When not provided, all content is cloned (current behavior). Existing clone callers are not affected.

• Risk: Templates accumulate and become hard to find.

  • Mitigation: Category filtering and search are built into the template picker from v1. Categories can be extended to tags in a future iteration.

Future Considerations

• Platform starter templates: ClassroomIO-provided templates shown in a separate "ClassroomIO Templates" section of the picker.
• AI-generated templates: "Generate with AI" as a third option in the course creation flow alongside "Blank" and "From Template."
• Template marketplace: Orgs opt-in to share templates publicly.
• Template versioning: Track changes and allow courses to "pull updates" from the source template.
• Template access control: Restrict which instructors can use or edit certain templates.
• Cohort integration: When course cohorts ship, templates could include default cohort configuration.