ulivargas/classroomio

Fork 0

Files

T

1e9a82e912 feat: complete rewrite of course (#622 )

* theming improvements

* border style improvements

* refactor: migrate org routes to server-side data fetching

Move client-side API calls to server-side load functions for better
performance, security, and SEO. Implement permission-based course filtering

* refactor: clean up course and community components

This commit removes unused components and files related to courses and community features, streamlining the codebase. It also updates various routes to enhance performance and maintainability. Additionally, it introduces new types and constants for better type safety and organization.

* refactor: fix video formatting on website and other styles

* refactor: update course and dashboard components for improved styling and functionality

* more icon improvements

* refactor: streamline course and dashboard components

This commit updates various course and dashboard components for improved styling and functionality. It includes the removal of unused files, updates to imports and exports, and enhancements to type safety. Additionally, it introduces new routes and optimizes existing ones for better performance and maintainability.

* refactor: enhance lesson completion logic

* chore: delete all emails on dashboard and move other api routes to backend.

move all emails to the backend and

* feat: Refactor API and database queries for courses, quizzes, and lessons, migrating Supabase functions and schema management.

* get app loading

* fix ui and build error of cio/api

* refactor: move direct database queries to query layer

- Create query functions: getCourseWithOrgData, getOrganizationByCourseId, updateCourseVersion, updateLessonsSectionId, getProfileByGroupMemberId, getQuestionTypesByIds
- Refactor services to use query functions instead of direct db queries
- Add transaction support to updateCourseVersion and updateLessonsSectionId
- Fix getProfileByGroupMemberId to return profile directly (not nested)
- Fix updateLessonsSectionId to use .returning() instead of rowCount

This aligns services with architecture pattern where services orchestrate queries rather than executing them directly.

* exercise saving improvements

* fix and optimise exercise creation

* refactor: update dialog components for improved styling and functionality

- Adjusted dialog content width and maximum constraints for better responsiveness.
- Changed heading font size for consistency in the new exercise modal.
- Replaced CloseIcon with CrossIcon for a more modern appearance in dialog close button.

* refactor: enhance course and exercise management components

- Introduced new components for exercise creation, editing, and viewing, improving user experience.
- Refactored existing lesson and exercise components for better organization and maintainability.
- Updated routing for exercises and lessons to streamline navigation within the course structure.
- Added new utility functions and constants to support content management across the application.

* feat: implement course content management API and UI components

- Added new API routes for updating and deleting course content, enhancing content management capabilities.
- Introduced new Svelte components for displaying and managing course content, including content lists and action handlers.
- Updated existing course routing to integrate new content management features.
- Refactored content-related utility functions for improved organization and maintainability.

* refactor: remove Supabase references and implement course section management

- Removed Supabase-related environment variables and Dockerfile arguments to streamline configuration.
- Introduced a new section management API with routes for creating, updating, deleting, and reordering course sections.
- Updated course services to handle section operations, ensuring consistency in course content management.
- Refactored existing lesson section logic to align with the new course section structure, enhancing maintainability.

* chore: update .prettierignore to exclude additional file types

- Added exclusions for SQL and environment files to the Prettier ignore list.
- Included Dockerfile and .prettierignore itself to prevent formatting issues.

* feat: enhance course content management with translation support and UI improvements

- Added translation keys for user-facing text in course-related components, ensuring all UI copy is sourced from translation files.
- Updated lesson and exercise creation components to utilize translation keys for success and error messages, improving localization.
- Refactored course content management components to streamline the creation and editing process, enhancing user experience.
- Introduced new constants for content options and stepper states to standardize component behavior and improve maintainability.
- Improved styling and functionality of course content modals and steppers for better user interaction.

* feat: enhance course content management and UI components

- Updated .prettierignore to exclude storybook-static directory.
- Improved exercise creation logic by refining option handling and adding UUID support for option values.
- Enhanced navigation component with debugging output for custom links.
- Introduced a new method in CourseApi to update content items locally, improving state management during navigation.
- Added caching for exercise templates by tag in ExerciseTemplateApi to optimize performance.
- Refactored lesson and exercise components for better organization and maintainability, including updates to modal styling and functionality.
- Implemented local patching for lesson and exercise list items to ensure UI consistency after updates.

* student + teacher invite (not fully tested)

* refactor: streamline course team member middleware

- Removed unnecessary console logging and timing for checking user permissions.
- Simplified the logic for determining if a user is a course team member or organization admin.

* reorder course sidebar to move content to its own page.

* feat: implement unified course enrollment route and API

- Introduced a new enrollment route `/course/:slug/enroll` to replace the previous invite system.
- Unified enrollment logic for free and paid courses, allowing direct enrollment for free courses and invite token validation for paid courses.
- Updated course landing page to redirect to the new enrollment route for free courses.
- Removed obsolete invite routes and related logic, streamlining the enrollment process.
- Enhanced API with a new `POST /course/:courseId/enroll` endpoint for handling enrollments.
- Added rate limiting for enrollment requests to prevent abuse.
- Updated UI components to reflect changes in enrollment flow and messaging.

* chore: update docker stack, docs, and auth token automation

* chore: make prettier check ignore unknown file types

* fix: avoid using authClient on server file and keep authClient client focused

* chore: always get the server on demand depending on the environment

* chore: update dashboard configuration and Docker setup for environment variables

- Modified the Svelte configuration to directly use the PUBLIC_SERVER_URL environment variable.
- Enhanced the Docker Compose file to include health check formatting and added environment variable arguments for the dashboard build.
- Updated the Dockerfile to echo environment variable values during the build process, ensuring clarity on the configuration being used.

* chore: enhance Docker setup and documentation for production deployment

- Added a new production Docker Compose file and example environment file for published images.
- Updated README and usage documentation to include instructions for deploying with production images.
- Modified Svelte configuration to standardize the use of the posthog domain.
- Removed unnecessary console logs from the API client and layout server files for cleaner output.
- Improved overall clarity in Docker documentation regarding self-hosting and image publishing.

* chore(db): log function name in query catch blocks (console.error 'funcName error:', error)

Co-authored-by: Cursor <[email protected]>

* fix: multiple refresh issue

* fix: server key not passed to api

* fix: clarify usage of PRIVATE_SERVER_KEY and AUTH_BEARER_TOKEN in documentation

- Updated documentation to specify that PRIVATE_SERVER_KEY is used for server-to-server API key authentication and is validated by API key middleware.
- Clarified that AUTH_BEARER_TOKEN is a separate token not utilized by apiKeyMiddleware.
- Adjusted examples in Docker setup and self-hosting documentation to reflect these changes.

* fix migration script

* fix: improve language handling and add database reset script

- Updated language extraction to handle potential undefined values, defaulting to 'en' if necessary.
- Added a new script for resetting the database, including functionality to truncate public tables and run setup with optional seeding.

* feat: add promote ungrouped section functionality and enhance document handling in dashboard

- Implemented a new API endpoint to promote synthetic "Ungrouped" content into a real persisted section, allowing for better organization of course materials.
- Updated the dashboard to include a new component for displaying content count badges for lessons and exercises.
- Enhanced document management features, including a new document card component with dropdown actions for viewing, downloading, and removing documents.
- Improved file upload handling with a dedicated file drop zone and error handling for file type and size restrictions.
- Refactored existing components for better readability and maintainability, including updates to lesson and document lists.

* chore: use root env file for docker compose

* docs: document docker no-build startup flow

* chore: add no-build option to docker full stack script

* fix(email): handle SMTP TLS mode by port

* feat(auth): add configurable cookie domain env and docs

* apps/dashboard/src/lib/utils/services/auth/session.ts

* fix(email): make sender configurable via SMTP_SENDER

* chore(i18n): regenerate locale translations and support language targeting

* chore(config): switch api to PUBLIC_SERVER_URL

* fix(i18n): persist selected locale across navigation

* feat(assets): implement organization asset management routes and services

- Added new routes for managing organization assets, including listing, creating, updating, deleting, and exporting assets.
- Introduced asset-related services for handling asset operations such as creation, retrieval, and deletion.
- Integrated YouTube metadata resolution and asset attachment/detachment functionalities.
- Updated organization routes to include the new asset management routes.
- Enhanced error handling for asset-related operations.

* fix(document-list): update conditional rendering for edit mode in document list

* debug self hosted layout setup

* refactor(sidebar): simplify lms sidebar footer and improve navigation item rendering

* feat: tags

* chore: tags roadmap + translations

* fix(api): add authMiddleware to exercise, invites, and content routers

- exerciseRouter: apply authMiddleware before courseMemberMiddleware on all 10 routes
- invitesRouter: apply authMiddleware before courseTeamMemberMiddleware on all 4 routes
- contentRouter: add authMiddleware to PUT route (DELETE already had it)

Both courseMemberMiddleware and courseTeamMemberMiddleware document requiring
authMiddleware to be applied first. This aligns with lessonRouter pattern and
ensures explicit middleware contract regardless of global session middleware.

Co-authored-by: Rotimi Best <[email protected]>

* fix(course): use courseTeamMemberMiddleware for PUT, DELETE, and analytics routes

These routes require admin/tutor role per JSDoc but were using
courseMemberMiddleware which allows any course member including students.
Switch to courseTeamMemberMiddleware to restrict access to ADMIN/TUTOR
group members and org admins.

Co-authored-by: Rotimi Best <[email protected]>

* chore: unify pricing component between dashboard and website (#630)

* feat: modularize pricing card

* feat: initia implementation of pricing togge

* fix: minor amendment

* refactor: update pricing components for improved layout and styling

- Adjusted spacing in the pricing card layout for better visual consistency.
- Modified button styles and sizes for enhanced usability.
- Cleaned up the pricing toggle component by removing unnecessary console logs and restructuring the button rendering logic.

* add handle click

* chore(css): update Tailwind CSS output with new utility classes and theme variables

* fix(api): enable orgMemberMiddleware for stats route

This change ensures that the stats route is protected by orgMemberMiddleware, aligning access control with other routes. Additionally, removed unnecessary console log from the layout server file to clean up the code.

---------

Co-authored-by: Rotimi Best <[email protected]>

* pass query parameter to signup from pricing page

* ui updates to pricing cards

* commit all PRDs

* add open api spec to api prd

* make blue default theme

* more prds

* sync option id sequence on question update

* docs: more classroomio features

* chore: more ui improvements

* docs: new component docs

* chore: CSP Configuration (#638)

* feat(validation): add GitHub repository name validation

- Add ZRepositoryName schema for validating GitHub repo names
- Add ZRepositoryOwner for owner/username validation
- Add ZRepositoryIdentifier for owner/repo format
- Follow GitHub rules: A-Za-z0-9_.-, 1-100 chars, reserved names
- Add translation keys for validation messages

Fixes #637

Co-authored-by: Rotimi Best <[email protected]>

* Revert "feat(validation): add GitHub repository name validation"

This reverts commit 3436536bb17a0f05b3a9fe8dd7682cde64dd1dce.

* feat(dashboard): make CSP external domains configurable via env

Move hardcoded external domains from svelte.config.js to .env configuration
for on-premise deployments with strict security policies, data residency
constraints, or CISO-driven allowlists.

- ALLOWED_EXTERNAL_DOMAINS: single list for all CSP directives
- CSP_SCRIPT_SRC_DOMAINS, CSP_STYLE_SRC_DOMAINS, CSP_CONNECT_SRC_DOMAINS,
  CSP_FRAME_SRC_DOMAINS, CSP_FONT_SRC_DOMAINS: per-directive override
- When unset, defaults retain current SaaS behavior (backward compatible)

Fixes #637

Co-authored-by: Rotimi Best <[email protected]>

* fix(dashboard): self-hosted CSP uses only env vars, no defaults

Co-authored-by: Rotimi Best <[email protected]>

* fix(dashboard): add all classroomio.com domains to CSP defaults

Co-authored-by: Rotimi Best <[email protected]>

* docs: add CSP ALLOWED_EXTERNAL_DOMAINS to self-hosting guides

Co-authored-by: Rotimi Best <[email protected]>

* feat(docker): pass CSP domain env vars as build args to dashboard

Co-authored-by: Rotimi Best <[email protected]>

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Rotimi Best <[email protected]>

* feat: add SSO and token authentication routes and services

- Introduced new routes for SSO and token authentication under the organization namespace.
- Implemented SSO connection management including creation, update, activation, and deletion.
- Added token authentication configuration with support for secret rotation and status retrieval.
- Enhanced error handling for SSO and token authentication processes.
- Updated existing routes and services to integrate new functionalities.
- Improved gradebook service to fetch student marks and exercises.
- Refactored API structure for better organization and maintainability.

* update translations

* fix: add PUBLIC_SERVER_URL to .env.example to prevent localhost fallback in production (#641)

Co-authored-by: Cursor Agent <[email protected]>

* feat: new exercise question types

* MinIO S3 storage backend (#639)

* feat(storage): add MinIO/S3-compatible object storage backend

- Add OBJECT_STORAGE_* env vars for generic S3-compatible backends (MinIO, AWS S3)
- Create storage config module with Cloudflare R2 fallback for backward compatibility
- Refactor s3.ts to use configurable client and bucket names from config
- Update media.ts to use provider-neutral public URL (OBJECT_STORAGE_MEDIA_PUBLIC_BASE_URL or CLOUDFLARE_IMAGE_BUCKET_DOMAIN)
- Add MinIO service and init to docker-compose (profile: minio) with videos/documents/media buckets
- Add localhost:9000 to dashboard CSP for local MinIO presigned URL uploads
- Update self-hosting and Cloudflare docs with MinIO option
- Update .env examples and docker USAGE.md

Fixes #635

Co-authored-by: Rotimi Best <[email protected]>

* docs: add MINIO_ROOT_USER and MINIO_ROOT_PASSWORD to self-hosting guides

Co-authored-by: Rotimi Best <[email protected]>

* feat(media): refactor media management and integrate MinIO support

- Updated media API to use a new `mediaApi` module, replacing `mediaManagerApi` references across components.
- Added MinIO configuration options to the Docker setup, allowing for optional object storage exclusion.
- Enhanced environment variable management for MinIO in the `.env.example` file.
- Updated Content Security Policy (CSP) to allow local MinIO access in the dashboard.
- Introduced new media components for asset management, including asset cards and usage dialogs.

This refactor improves the modularity of the media handling system and provides better support for S3-compatible storage solutions.

* feat(dashboard): enhance logging and refactor auth session handling

- Added console logging for event and environment variables in hooks.server.ts to aid debugging.
- Refactored auth session handling to use authServerClient instead of authClient in session.ts for improved consistency.
- Updated Dockerfile to ensure the dashboard build output is present before starting the application.
- Expanded self-hosting documentation to include troubleshooting steps for disk space issues in PostgreSQL and Docker.

These changes improve the observability of the application and streamline the authentication process.

* refactor(dashboard): remove debug logging and enhance Postgres healthcheck

- Removed console logging for event and environment variables in hooks.server.ts to clean up the code.
- Updated Postgres healthcheck in docker-compose.yaml to require a successful `SELECT 1` query, ensuring dependent services only start once the database is ready.
- Expanded self-hosting documentation to include troubleshooting steps for database recovery issues.

These changes improve code clarity and reliability in service startup sequences.

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Rotimi Best <[email protected]>

* feat: add Plyr media player icons and PDF.js integration

- Introduced new Plyr SVG icons for media player controls in both course and dashboard applications.
- Updated Plyr player configuration to use local icon assets.
- Integrated PDF.js for document viewing, replacing external CDN links with local paths for improved performance and reliability.
- Enhanced PDF viewer modal z-index for better visibility.

This update improves the media player experience and ensures consistent access to necessary resources.

* feat: enhance account and organization services with type definitions and promise return types

- Updated `getAccountData` to return a structured result type including profile and organizations.
- Modified `getOrganizationsWithFilters` to specify a promise return type for better type safety.
- Added new type imports for organization-related data structures to improve clarity and maintainability.

These changes improve type safety and enhance the overall structure of the account and organization services.

* feat: implement Redis caching for presigned URLs and refactor API interactions

- Added Redis caching for presigned download URLs in the API to reduce redundant S3 calls, improving performance.
- Introduced a new `PresignApi` class in the frontend to centralize presigned URL requests, enhancing code maintainability.
- Updated various components to utilize the new `presignApi` methods for document and video upload/download operations.
- Enhanced error handling for Redis operations to ensure graceful degradation in case of cache failures.

These changes optimize the presigned URL generation process and streamline API interactions across the application.

* fix: add better-auth dependency to dashboard (#645)

* chore: unify exercise answer data format

* feat: make selfhosting run under one org for simplicity (#647)

* feat: implement self-hosting PRD + license key system

Self-hosting single-org:
- Add PUBLIC_IS_SELFHOSTED to API env, block org creation when org exists
- Auto-add non-members as students in GET /account bootstrap
- getOrgSiteInfo: root domain returns single org for self-hosted
- App init: route to /lms when self-hosted + no orgs
- Hide org switcher and Add Org modal when self-hosted

Invite-only signup:
- Add settings.signup.inviteOnly via ZUpdateOrganization
- Allow public signups toggle in org auth settings
- Signup page: hide form when invite-only and no invite context
- Landing page nav: respect inviteOnly for signup link

First signup auto-verify:
- Self-hosted first signup (no orgs) auto-verifies email in createProfileHook

License key system:
- LICENSE_KEY, LICENSE_VERIFICATION_URL for external verification API
- Feature gates: SSO, token-auth, no-tracking (PostHog/Senja)
- requireLicense middleware for API routes
- Dashboard: license store, gate PostHog/Senja/SSO/token-auth UI
- docs/LICENSE_API_CONTRACT.md for external API spec

Co-authored-by: Rotimi Best <[email protected]>

* feat: get rid of carbon completely

* chore: license verification happens only for selfhosted instance

* fix: in self hosted instance, orgSite is the default

* docs: how to write math in cio editor

* Update packages/db/src/queries/organization/organization.ts

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

* Update apps/api/src/services/license.ts

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

* fix: translations, cursor pr reviews, simplify license fetching and check

* refactor: update analytics setup for cloud and self-hosted deployments; enhance settings merge logic

* refactor: update license fetching URL for development environment; optimize organization query to prevent plan row loss

* more selfhosting improvements

* feat: enhance signup guard for self-hosted instances by requiring organization context when no org ID is provided

* pr reviews

* fix: correct query parameter handling in course navigation

* pr reviews

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Rotimi Best <[email protected]>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

---------

Co-authored-by: Cursor <[email protected]>
Co-authored-by: Rotimi Best <[email protected]>
Co-authored-by: Abdulmuizz Hamzat <[email protected]>
Co-authored-by: Adeyemi Adetunji <[email protected]>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

2026-03-09 11:18:22 +01:00

30 KiB

Raw Blame History

Exercise Question Types Expansion - Implementation Plan

Scope Lock (v1)

Keep legacy RADIO, CHECKBOX, TEXTAREA behavior backward compatible.
Deliver P0 question types first: TRUE_FALSE, SHORT_ANSWER, NUMERIC, FILL_BLANK, FILE_UPLOAD.
Manual grading is required when exercise includes SHORT_ANSWER or TEXTAREA.
Attempt rules are exercise-level: maxAttempts, attemptScoringRule (highest, latest, average).
Correct-answer visibility is exercise-level policy.
File upload is one file per question in v1.
Upload limits are plan based: free 2MB, paid 10MB.
Use one canonical question-type registry to remove scattered hardcoded numeric IDs.
Existing submissions continue to read from answers[] and openAnswer during migration.
New type-rich answers write to question_answer.payload.
DB update policy for this plan: apply DB changes only in packages/db/src/schema.ts; do not generate new files in packages/db/src/migrations.
Question-type registry/contracts/state/serialization logic must live in @cio/question-types; @cio/ui must stay components-only.
Shared packages must be app-agnostic (no dashboard-local imports), so other apps can build exercise/form products from the same package APIs.
Exercise-level auto-grade toggle can be enabled only when all active questions are auto-gradable; if not, it stays disabled with a hint message.
Grading engine remains in apps/api as backend source of truth and is locked behind API contracts; no standalone grading package is introduced.
Submission grading workflow truth uses explicit submission.gradingState and submission.overallStatus; legacy submission.statusId is retained as board compatibility projection only.
Initial grading state on student submit is always queued.
Server-owned grading transitions are: queued -> processing -> completed, queued -> processing -> awaiting_manual -> completed, and queued -> processing -> failed -> queued (retry path).
overallStatus classification values are auto_graded, manual_required, and hybrid, computed deterministically from attempt snapshot and question capabilities.
Client routes do not directly own grading workflow transitions; API/service layer validates and applies allowed transitions.
Renderer filenames must not repeat mode suffix; canonical naming is renderers/{question-type}/{mode}.svelte (for example renderers/true-false/edit.svelte, not true-false-edit.svelte).
@cio/ui/custom/exercise-question must not contain hardcoded user-facing English strings (labels, helper text, placeholders, tooltips, validation messages, sr-only text); host app provides copy through render contracts/props.

Delivery Phases

Phase A: Foundation (schema, seeds, shared registry, validation contracts)
Phase B: API + grading + submission state engine for P0
Phase C: Dashboard authoring/taking/grading UX for P0
Phase D: P1 types (MATCHING, ORDERING)
Phase E: P2 type (HOTSPOT)
Phase F: Regression hardening, rollout, and monitoring

Shared Package File Contract (Cross-App Reuse)

These files are required deliverables so any app in the monorepo can consume shared packages and build a standalone exercise/forms product.

`@cio/question-types` package files

packages/question-types/src/question-type-keys.ts
packages/question-types/src/question-type-types.ts
packages/question-types/src/question-type-registry.ts
packages/question-types/src/question-type-lookup.ts
packages/question-types/src/question-type-capabilities.ts
packages/question-types/src/question-answer-payload.ts
packages/question-types/src/question-scoring-rules.ts
packages/question-types/src/exercise-types.ts
packages/question-types/src/render-contract.ts
packages/question-types/src/form-state.ts
packages/question-types/src/answer-serializer.ts
packages/question-types/src/renderer-registry.ts
packages/question-types/src/index.ts
packages/question-types/package.json (package name: @cio/question-types)

`@cio/ui` shared exercise-question component files (core)

packages/ui/src/custom/exercise-question/question-form-root.svelte
packages/ui/src/custom/exercise-question/question-navigation.svelte
packages/ui/src/custom/exercise-question/question-renderer.svelte
packages/ui/src/custom/exercise-question/question-list.svelte
packages/ui/src/custom/exercise-question/renderer-contract.ts
packages/ui/src/custom/exercise-question/index.ts
packages/ui/src/index.ts (exports ./custom/exercise-question)

`@cio/ui` P0 renderer files

packages/ui/src/custom/exercise-question/renderers/radio/edit.svelte
packages/ui/src/custom/exercise-question/renderers/checkbox/edit.svelte
packages/ui/src/custom/exercise-question/renderers/textarea/edit.svelte
packages/ui/src/custom/exercise-question/renderers/radio/take.svelte
packages/ui/src/custom/exercise-question/renderers/checkbox/take.svelte
packages/ui/src/custom/exercise-question/renderers/textarea/take.svelte
packages/ui/src/custom/exercise-question/renderers/radio/preview.svelte
packages/ui/src/custom/exercise-question/renderers/checkbox/preview.svelte
packages/ui/src/custom/exercise-question/renderers/textarea/preview.svelte
packages/ui/src/custom/exercise-question/renderers/true-false/edit.svelte
packages/ui/src/custom/exercise-question/renderers/short-answer/edit.svelte
packages/ui/src/custom/exercise-question/renderers/numeric/edit.svelte
packages/ui/src/custom/exercise-question/renderers/fill-blank/edit.svelte
packages/ui/src/custom/exercise-question/renderers/file-upload/edit.svelte
packages/ui/src/custom/exercise-question/renderers/true-false/take.svelte
packages/ui/src/custom/exercise-question/renderers/short-answer/take.svelte
packages/ui/src/custom/exercise-question/renderers/numeric/take.svelte
packages/ui/src/custom/exercise-question/renderers/fill-blank/take.svelte
packages/ui/src/custom/exercise-question/renderers/file-upload/take.svelte
packages/ui/src/custom/exercise-question/renderers/true-false/preview.svelte
packages/ui/src/custom/exercise-question/renderers/short-answer/preview.svelte
packages/ui/src/custom/exercise-question/renderers/numeric/preview.svelte
packages/ui/src/custom/exercise-question/renderers/fill-blank/preview.svelte
packages/ui/src/custom/exercise-question/renderers/file-upload/preview.svelte

`@cio/ui` P1/P2 renderer files (created when phase starts)

packages/ui/src/custom/exercise-question/renderers/matching/edit.svelte
packages/ui/src/custom/exercise-question/renderers/matching/take.svelte
packages/ui/src/custom/exercise-question/renderers/matching/preview.svelte
packages/ui/src/custom/exercise-question/renderers/ordering/edit.svelte
packages/ui/src/custom/exercise-question/renderers/ordering/take.svelte
packages/ui/src/custom/exercise-question/renderers/ordering/preview.svelte
packages/ui/src/custom/exercise-question/renderers/hotspot/edit.svelte
packages/ui/src/custom/exercise-question/renderers/hotspot/take.svelte
packages/ui/src/custom/exercise-question/renderers/hotspot/preview.svelte

Renderer Filename Convention (Locked)

Question type is expressed by folder: renderers/{question-type}/.
Mode is expressed only by filename: edit.svelte, take.svelte, preview.svelte.
Do not use mode-first folders (renderers/edit/*) or redundant suffixes like -edit, -take, or -preview.

UI Copy Ownership (Locked)

Shared UI renderers are copyless primitives and must not embed end-user copy.
All labels/help/error/tooltip/placeholder/sr-only text must be provided by host app (dashboard) via typed contract props.
Translation key resolution stays in host apps (apps/dashboard), not in packages/ui.
Renderer utilities in packages/ui must not generate user-facing fallback words (for example Step); fallback semantics must come from host-provided copy.

Ticket Breakdown

ID	Phase	Area	Task	Key Files	Dependencies	Done When
EX-A1	A	DB Schema	Add new columns for `exercise`, `question`, `question_answer`, `submission` (attempt controls, settings, payload, grading metadata including workflow/classification fields) in schema only	`packages/db/src/schema.ts`	None	Schema changes compile via package builds and no new migration files are generated
EX-A2	A	DB Seed	Extend `question_type` seed with new typenames/labels	`packages/db/src/utils/seed/questionType.ts`	EX-A1	Re-seeding inserts missing types idempotently
EX-A3	A	Shared Registry	Create canonical question type registry and metadata in dedicated package (`@cio/question-types`)	`packages/question-types/src/question-type-keys.ts`, `packages/question-types/src/question-type-types.ts`, `packages/question-types/src/question-type-registry.ts`, `packages/question-types/src/question-type-lookup.ts`, `packages/question-types/src/question-type-capabilities.ts`, `packages/question-types/src/question-answer-payload.ts`, `packages/question-types/src/question-scoring-rules.ts`, `packages/question-types/src/exercise-types.ts`, `packages/question-types/src/render-contract.ts`, `packages/question-types/src/form-state.ts`, `packages/question-types/src/answer-serializer.ts`, `packages/question-types/src/renderer-registry.ts`, `packages/question-types/src/index.ts`, `packages/question-types/package.json`	EX-A2	API and dashboard consume one source of truth for type keys/traits and all shared registry files exist
EX-A4	A	Validation	Replace fragile numeric-only assumptions with registry-backed schemas and enums	`packages/utils/src/validation/constants.ts`, `packages/utils/src/validation/exercise/exercise.ts`	EX-A3	Validation accepts legacy + new types and rejects invalid per-type payloads
EX-A5	A	DB Queries	Add read/write support for new columns and typed answer payload in query layer	`packages/db/src/queries/exercise/exercise.ts`, `packages/db/src/queries/submission/*`	EX-A1	Query methods persist and return settings/payload/attempt fields
EX-A6	A	Clone Safety	Fix clone question type mismatch (`TEXTAREA` id bug) using shared constant/typename	`apps/api/src/services/course/clone.ts`	EX-A3	Exercise clone preserves paragraph questions and options correctly
EX-A7	A	Shared Copy Contract	Add typed i18n/copy contract for exercise-question renderer labels and messages in shared question-types package	`packages/question-types/src/render-contract.ts`, `packages/question-types/src/exercise-types.ts`, `packages/question-types/src/index.ts`, `packages/question-types/src/renderer-registry.ts`	EX-A3	Host apps can pass a strongly typed labels object that covers shared renderer copy needs
EX-B1	B	API Validation	Split exercise schemas into base + per-type authoring/submission schemas	`packages/utils/src/validation/exercise/*`	EX-A4	Route-level validation is discriminated by question type
EX-B2	B	Exercise Service	Support create/update with `question.settings`, `scoringMode`, `manualGradingRequired`, and exercise attempt settings	`apps/api/src/services/exercise/exercise.ts`, `apps/api/src/services/exercise/utils.ts`	EX-A5, EX-B1	Create/update persists all new fields and returns normalized exercise DTO
EX-B3	B	Submission Service	Accept typed answers into `question_answer.payload` while preserving legacy fallback fields	`apps/api/src/services/submission/submission.ts`	EX-A5, EX-B1	Submission creation supports mixed legacy/new question payloads
EX-B4	B	Grading Engine	Implement auto-grading for P0 objective types (`TRUE_FALSE`, `NUMERIC`, `FILL_BLANK`)	`apps/api/src/services/submission/submission.ts`, `apps/api/src/services/exercise/utils.ts`	EX-B3	Auto-grade computed at question level with configurable scoring mode
EX-B5	B	Attempt Rules	Enforce `maxAttempts` and compute final score by `attemptScoringRule`	`apps/api/src/services/submission/submission.ts`, `packages/db/src/queries/submission/*`	EX-B3	New attempts blocked when limit reached; final score follows configured rule
EX-B6	B	Upload Handling	Add file-upload answer flow with allowed type/size validation and asset reference storage	`apps/api/src/routes/course/exercise.ts`, `apps/api/src/services/submission/submission.ts`	EX-B3	Invalid upload types/sizes rejected; valid uploads linked in answer payload
EX-B7	B	Routes	Update exercise and submission routes for new request/response contracts	`apps/api/src/routes/course/exercise.ts`, `apps/api/src/routes/course/submission.ts`	EX-B2, EX-B3	RPC contract supports new fields without breaking legacy clients
EX-B8	B	Manual Grading	Route mixed/manual exercises to manual grading path and allow override of auto score	`apps/api/src/services/submission/submission.ts`, `apps/api/src/services/mark/gradebook.ts`	EX-B4	Teacher can override and persist final grade on submission
EX-B9	B	Auto-Grade Guardrail	Enforce exercise-level `auto-grade` eligibility in API/service layer using question-type capability checks	`apps/api/src/services/exercise/exercise.ts`, `apps/api/src/services/submission/submission.ts`, `packages/question-types/src/question-type-capabilities.ts`	EX-A3, EX-B2	API rejects `auto-grade=true` when any active question type requires manual grading
EX-B10	B	Submission Workflow	Implement API-owned grading state machine and deterministic `overallStatus` computation on submission lifecycle	`packages/db/src/schema.ts`, `packages/utils/src/validation/submission/submission.ts`, `packages/db/src/queries/submission/submission.ts`, `apps/api/src/services/submission/submission.ts`, `apps/api/src/routes/course/submission.ts`	EX-A1, EX-B3, EX-B4, EX-B8	Submit starts `queued`, transitions are validated server-side, and invalid direct state jumps are rejected
EX-B11	B	Board Compatibility	Preserve existing 3 board columns by projecting workflow state to legacy `statusId` (`1=Submitted`, `2=In Progress`, `3=Graded`) in API responses	`apps/api/src/services/submission/submission.ts`, `apps/api/src/routes/course/submission.ts`, `packages/db/src/queries/submission/submission.ts`	EX-B10	Submission board endpoints continue returning stable `statusId` while grading truth lives in workflow/classification fields
EX-C1	C	Dashboard Types	Add request/response/data types for new exercise payloads in feature types	`apps/dashboard/src/lib/features/course/utils/types.ts`	EX-B7	Frontend types inferred from API contract only
EX-C2	C	Dashboard API	Update exercise API class to validate/send new create/update/submit payload shapes	`apps/dashboard/src/lib/features/course/api/exercise.svelte.ts`	EX-C1	Create/update/submit flows pass new schema checks client-side
EX-C3	C	Renderer Registry	Implement registry logic in `@cio/question-types` and wire dashboard to map question-type keys to shared `@cio/ui` renderer components	`packages/question-types/src/renderer-registry.ts`, `packages/question-types/src/exercise-types.ts`, `packages/question-types/src/index.ts`, `packages/ui/src/custom/exercise-question/index.ts`, `packages/ui/src/index.ts`, `apps/dashboard/src/lib/features/course/components/exercise/edit-mode.svelte`, `apps/dashboard/src/lib/features/course/components/exercise/view-mode.svelte`	EX-A3	No hardcoded `if RADIO/CHECKBOX/TEXTAREA` branching remains; registry/contracts come from `@cio/question-types` and components from `@cio/ui`
EX-C4	C	Edit UX	Refactor authoring UI to use registry and per-type settings editors	`apps/dashboard/src/lib/features/course/components/exercise/edit-mode.svelte`	EX-C3, EX-C2	Instructor can configure P0 types and per-type settings in one flow
EX-C5	C	Take UX	Refactor learner view to use registry and typed answer serializers	`apps/dashboard/src/lib/features/course/components/exercise/view-mode.svelte`, `apps/dashboard/src/lib/features/course/components/exercise/functions.ts`	EX-C3, EX-C2	Student can answer mixed-type exercises and submit valid payload
EX-C6	C	Store	Update exercise store/autosave model for typed answers and migration-safe hydration	`apps/dashboard/src/lib/features/course/components/exercise/store.ts`	EX-C5	Autosave/restore works for legacy and new type payloads
EX-C7	C	P0 Components	Add new UI question components (`true-false`, `short-answer`, `numeric`, `fill-blank`, `file-upload`) in shared UI package	`packages/ui/src/custom/exercise-question/renderers/true-false/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/short-answer/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/numeric/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/fill-blank/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/file-upload/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/true-false/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/short-answer/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/numeric/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/fill-blank/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/file-upload/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/true-false/preview.svelte`, `packages/ui/src/custom/exercise-question/renderers/short-answer/preview.svelte`, `packages/ui/src/custom/exercise-question/renderers/numeric/preview.svelte`, `packages/ui/src/custom/exercise-question/renderers/fill-blank/preview.svelte`, `packages/ui/src/custom/exercise-question/renderers/file-upload/preview.svelte`, `packages/ui/src/custom/exercise-question/index.ts`, `packages/ui/src/index.ts`	EX-C3	Edit/view/preview components exist for all P0 types and are exported from `@cio/ui`
EX-C8	C	Grading UI	Update submission/grading views to display typed answers from payload	`apps/dashboard/src/lib/features/course/components/exercise/submissions/*`	EX-B8, EX-C5	Teacher can review and grade all P0 answer shapes
EX-C9	C	i18n	Add translation keys for new types/settings/status copy	`apps/dashboard/src/lib/utils/translations/en.json`	EX-C4, EX-C5	No new hardcoded user-facing text
EX-C10	C	Accessibility	Validate keyboard navigation and mobile rendering for new question interactions in shared UI component package	`packages/ui/src/custom/exercise-question/*`	EX-C7	P0 UI passes accessibility checks and mobile smoke tests
EX-C11	C	Edit UX Guardrail	Add exercise-level `auto-grade` toggle, disable state, and hint copy when question mix includes manual-only types	`apps/dashboard/src/lib/features/course/components/exercise/edit-mode.svelte`, `apps/dashboard/src/lib/features/course/components/exercise/question-type-utils.ts`, `apps/dashboard/src/lib/utils/translations/en.json`	EX-C3, EX-B9	Toggle enables only when all active question types are auto-gradable; hint appears under toggle when blocked
EX-C12	C	Submission Board UX	Consume API workflow data while keeping 3-column board UX, and surface failed/manual-needed hints under In Progress column	`apps/dashboard/src/lib/features/course/pages/submissions.svelte`, `apps/dashboard/src/lib/features/course/components/exercise/mark-exercise-modal.svelte`, `apps/dashboard/src/lib/features/course/utils/types.ts`, `apps/dashboard/src/lib/features/course/api/submission.svelte.ts`, `apps/dashboard/src/lib/utils/translations/en.json`	EX-B10, EX-B11	Board still behaves as `1/2/3` columns, with additional workflow clarity from API-provided grading fields
EX-C13	C	Renderer Structure Refactor	Refactor shared renderer files to question-type folders with mode file names and update imports/registry/storybook references	`packages/ui/src/custom/exercise-question/renderers//edit.svelte`, `packages/ui/src/custom/exercise-question/renderers//take.svelte`, `packages/ui/src/custom/exercise-question/renderers//preview.svelte`, `packages/ui/src/custom/exercise-question/index.ts`, `packages/question-types/src/renderer-registry.ts`, `packages/storybook/src/molecules/exercise-question/`, `apps/dashboard/src/lib/features/course/components/exercise/*`	EX-C3, EX-C7	Renderer paths use `renderers/{question-type}/{mode}.svelte`; no mode-first folders or mode-suffixed filenames remain
EX-C14	C	Copy Externalization	Remove hardcoded user-facing copy from shared question renderer files and wire host-provided labels from dashboard translations	`packages/ui/src/custom/exercise-question/question-renderer.svelte`, `packages/ui/src/custom/exercise-question/question-navigation.svelte`, `packages/ui/src/custom/exercise-question/renderers//edit.svelte`, `packages/ui/src/custom/exercise-question/renderers//take.svelte`, `packages/ui/src/custom/exercise-question/renderers//preview.svelte`, `packages/ui/src/custom/exercise-question/renderers/ordering-utils.ts`, `apps/dashboard/src/lib/features/course/components/exercise/edit-mode.svelte`, `apps/dashboard/src/lib/features/course/components/exercise/view-mode.svelte`, `apps/dashboard/src/lib/features/course/utils/types.ts`, `apps/dashboard/src/lib/utils/translations/en.json`, `packages/storybook/src/molecules/exercise-question/`	EX-A7, EX-C3	Shared renderer package has no hardcoded end-user copy; dashboard injects all labels/messages from translation keys through typed contracts
EX-D1	D	Matching Type	Implement `MATCHING` schema, authoring/taking UI in shared UI component package, serializer, and grader	validation, API service, `packages/ui/src/custom/exercise-question/renderers/matching/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/matching/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/matching/preview.svelte`	EX-C7, EX-B4	Matching questions can be authored, submitted, and auto-graded
EX-D2	D	Ordering Type	Implement `ORDERING` schema, drag-sort UI in shared UI component package, serializer, and grader	validation, API service, `packages/ui/src/custom/exercise-question/renderers/ordering/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/ordering/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/ordering/preview.svelte`	EX-C7, EX-B4	Ordering questions can be authored, submitted, and auto-graded
EX-D3	D	Partial Credit	Add partial-credit policy controls and explainability in grading details	`apps/api/src/services/submission/submission.ts`, submissions UI	EX-D1, EX-D2	Teacher sees per-question partial-credit breakdown
EX-E1	E	Hotspot Type	Implement `HOTSPOT` schema, image coordinate payload, authoring/taking UI in shared UI component package, grader	validation, API service, `packages/ui/src/custom/exercise-question/renderers/hotspot/edit.svelte`, `packages/ui/src/custom/exercise-question/renderers/hotspot/take.svelte`, `packages/ui/src/custom/exercise-question/renderers/hotspot/preview.svelte`	EX-C7	Hotspot is fully supported end-to-end
EX-E2	E	Hotspot Hardening	Improve responsive/touch behavior and precision tolerances for hotspot grading	hotspot UI + grading utilities	EX-E1	Hotspot works reliably on mobile/tablet and desktop
EX-F1	F	API Tests	Add create/update/submit tests per type, attempt rules, manual/auto grading paths	`apps/api/tests/`, `packages/utils/src/validation/`	EX-B8, EX-D3, EX-E1	Core API behavior covered with passing tests
EX-F2	F	Dashboard Tests	Add component/store/integration tests for authoring, taking, autosave, submission payloads across dashboard integration and shared UI component package	`apps/dashboard/src/lib/features/course/components/exercise/`, `packages/ui/src/custom/exercise-question/`	EX-C10, EX-D2, EX-E2	UI and store behavior stable for legacy + new types
EX-F3	F	Regression	Add clone and backward-compat regression tests for legacy question data	API/services/db test files	EX-A6, EX-F1	Existing exercises run unchanged after rollout
EX-F4	F	Rollout	Ship rollout checklist, migration runbook, and monitoring for submission/grading errors	`prd/exercise-question-types/README.md`, ops docs/config	EX-F1, EX-F2, EX-F3	Controlled release enabled with rollback steps documented

Acceptance Criteria by Phase

Phase A

Schema changes are limited to packages/db/src/schema.ts and no migration files are generated.
question_type seed is idempotent and includes all planned typenames.
Shared registry is imported by both API and dashboard.
Clone service no longer depends on mismatched hardcoded paragraph ID.
Shared renderer copy-contract types are defined in @cio/question-types and exported for host apps.

Phase B

Exercise create/update APIs accept and return new settings fields.
Submission API accepts typed payloads and still reads legacy answer shape.
Attempt limits and scoring rules are enforced server-side.
File-upload answer validations enforce plan limits and allowed types.
API/service layer blocks exercise-level auto-grade when question mix includes any manual-only type.
Student submit always creates submission with workflow state queued and board-compatible statusId=1.
API enforces valid grading transitions only (queued -> processing -> ...), with retry path (failed -> queued), and rejects invalid direct client transitions.
overallStatus is computed deterministically as auto_graded, manual_required, or hybrid.
API projects workflow states to board statusId mapping (queued=1, processing|awaiting_manual|failed=2, completed=3).

Phase C

Authoring and learner UIs support all P0 types.
Renderer registry removes hardcoded question-type branching in core screens.
Dashboard consumes registry/contracts from @cio/question-types and renderer components from @cio/ui, not dashboard-local question renderer files.
Grading UI can render typed payloads for teacher review.
No hardcoded UI copy is introduced.
Shared package files listed in Shared Package File Contract are implemented and exported.
Exercise-level auto-grade toggle is disabled with a clear hint when question mix is not fully auto-gradable.
Submission board continues to use 3 columns from backend-projected statusId, while exposing workflow hints (failed, awaiting_manual) without changing board IA.
Renderer files/imports follow canonical type-first paths: renderers/{question-type}/{mode}.svelte.
@cio/ui/custom/exercise-question does not contain hardcoded end-user copy; dashboard passes translated labels/messages via typed render contracts.

Phase D

Matching and ordering are fully authorable/submittable/gradable.
Partial-credit configuration and score explanation are visible to instructors.

Phase E

Hotspot works with responsive image rendering and touch input.
Hotspot grading handles coordinate tolerances consistently.

Phase F

Regression tests cover legacy three types and mixed-type exercises.
Rollout checklist includes migration, monitoring, and rollback steps.

Verification Commands

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

Suggested First Sprint Slice

EX-A1 to EX-A7 (schema, seed, registry, validation foundation, clone fix, shared copy contract)
EX-B1 to EX-B5 + EX-B10 + EX-B11 (P0 API contracts, typed submission, attempt/scoring enforcement, workflow state machine, board projection compatibility)
EX-C1 to EX-C6 + EX-C14 (frontend types/API + renderer registry + core edit/view/store refactor + shared copy externalization)

This slice establishes the core contracts and de-risks the hardest migration paths before adding all P0 components and grading UI polish.

Implementation Progress (Updated Feb 26, 2026)

Completed ticket IDs:

EX-A3 Shared question-type package (@cio/question-types) with registry/contracts/helpers.
EX-A6 Clone safety bug fix using shared question type IDs.
EX-A7 Shared copy contract typing for renderer labels/messages (ExerciseQuestionLabels) in @cio/question-types.
EX-C3 Dashboard/UI renderer registry centralization (@cio/question-types contracts + @cio/ui components).
EX-C7 Shared @cio/ui/custom/exercise-question renderer component set delivered (includes P0 and additional renderer files used by current branch).
EX-C13 Renderer structure refactor completed with canonical type-first paths (renderers/{question-type}/{mode}.svelte) and updated imports/exports/storybook wiring.
EX-C14 Shared renderer copy externalization completed; dashboard now injects labels/messages from translations through typed contracts.

In-progress ticket IDs:

EX-A4 Validation migration is partial (constants wired to shared IDs; full per-type schema split still pending).
EX-C4 Authoring UX refactor is mostly done, but exercise-level grading controls/guards are not complete.
EX-C5 Learner UX refactor is active; answer submission/grading remains mixed legacy behavior.
EX-B10 Submission workflow state machine has been started (schema fields + transition validation + API projection wiring); lifecycle hardening and tests remain.
EX-B11 Board compatibility projection has been started (workflow-to-legacy statusId projection in submission service); endpoint/test hardening remains.
EX-C12 Dashboard board workflow hint wiring has been started (workflow hints + guarded transitions in board UI); full UX/polish and edge-case handling remain.
EX-D1, EX-D2, EX-E1 UI renderers exist, but full API validation/submission/grader paths are not complete.

30 KiB Raw Blame History