From 133f491fbd42e2aaf0eb8c3c9ee6d3218dcadbc8 Mon Sep 17 00:00:00 2001 From: NiloCK Date: Fri, 4 Jul 2025 16:16:15 -0300 Subject: [PATCH 1/5] [docs] add docs for studio-mode in static courses --- packages/cli/src/utils/template.ts | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/packages/cli/src/utils/template.ts b/packages/cli/src/utils/template.ts index 694ce563f..39851a734 100644 --- a/packages/cli/src/utils/template.ts +++ b/packages/cli/src/utils/template.ts @@ -413,8 +413,34 @@ npm run dev Build for production: \`\`\`bash npm run build +\`\`\`${ + config.dataLayerType === 'static' + ? ` + +## Studio Mode (Content Editing) + +This project supports **Studio Mode** - a content editing web interface for modifying course data: + +\`\`\`bash +npm run studio \`\`\` +Studio mode provides: +- **Visual Course Editor**: Interactive interface for editing course content +- **Live Preview**: See changes immediately in the browser +- **Hot Reload**: Changes are saved automatically to your course files +- **No Setup Required**: Built into the Skuilder CLI - just run the command + +When you run \`npm run studio\`, it will: +1. Start a local CouchDB instance for temporary editing +2. Load your course data from \`public/static-courses/\` +3. Launch the studio interface at http://localhost:7174 +4. Save changes back to your static course files when you flush + +**Important**: Studio mode **overwrites** existing static data source files in \`public/static-courses/\`. Make sure to commit or backup your course data before making major edits.` + : '' + } + ## Configuration Course configuration is managed in \`skuilder.config.json\`. You can modify: From b21b62327c191b429db4c5372fcfc1757d501fd0 Mon Sep 17 00:00:00 2001 From: NiloCK Date: Fri, 4 Jul 2025 19:48:45 -0300 Subject: [PATCH 2/5] add inline cli docs for studio cmd --- packages/cli/src/commands/studio.ts | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/commands/studio.ts b/packages/cli/src/commands/studio.ts index 24c46c5b0..fb5ee1005 100644 --- a/packages/cli/src/commands/studio.ts +++ b/packages/cli/src/commands/studio.ts @@ -14,11 +14,35 @@ const __dirname = dirname(__filename); export function createStudioCommand(): Command { return new Command('studio') - .description('Launch studio mode for editing a static course') + .description('Launch studio mode: a complete course editing environment with CouchDB, Express API, and web editor') .argument('[coursePath]', 'Path to static course directory', '.') .option('-p, --port ', 'CouchDB port for studio session', '5985') .option('--no-browser', 'Skip automatic browser launch') - .action(launchStudio); + .action(launchStudio) + .addHelpText('after', ` +Studio Mode creates a full editing environment for static courses: + + Services Started: + • CouchDB instance (Docker) on port 5985+ for temporary editing + • Express API server on port 3001+ for backend operations + • Studio web interface on port 7174+ for visual editing + + Workflow: + 1. Loads course data from public/static-courses/ into CouchDB + 2. Opens web editor for visual course content editing + 3. Use "Flush to Static" to save changes back to your course files + 4. Studio mode overwrites source files - backup before major edits + + Requirements: + • Docker (for CouchDB instance) + • Valid static course project (with package.json) + • Course data in public/static-courses/ directory + + Example: + skuilder studio # Launch in current directory + skuilder studio ./my-course # Launch for specific course + skuilder studio --port 6000 # Use custom CouchDB port + skuilder studio --no-browser # Don't auto-open browser`); } interface StudioOptions { From 71dd9e8766d282c377423bc8ad6021f49c8d9956 Mon Sep 17 00:00:00 2001 From: NiloCK Date: Fri, 4 Jul 2025 19:49:32 -0300 Subject: [PATCH 3/5] add instructions for pack, unpack, studio cmds --- packages/cli/README.md | 130 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 122 insertions(+), 8 deletions(-) diff --git a/packages/cli/README.md b/packages/cli/README.md index 07a1deba2..735aa07b9 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -2,6 +2,14 @@ A command-line tool for scaffolding Skuilder course applications. +A Skuilder course consists of: +- a Vue.js application +- a data layer (static or dynamic) + +Static data-layer courses are self-contained as JSON files, and can be deployed as a static site. + +Dynamic data-layer courses are served from a CouchDB database and require a more involved setup ⚠️ **which is not currently well documented** ⚠️. + ## Installation Install globally via npm: @@ -16,9 +24,11 @@ Or use npx to run without installing: npx skuilder init my-course ``` -## Usage +## Commands + +### Project Initialization -### Create a new project +#### Create a new project ```bash skuilder init my-anatomy-course @@ -29,9 +39,9 @@ This will start an interactive prompt to configure your project: - Data layer type (static or dynamic) - CouchDB connection details (for dynamic) - Theme selection -- Course ID to import (optional) +- Course ID to import (optional import from a live CouchDB server) -### Non-interactive mode +#### Non-interactive mode ```bash skuilder init physics-101 \ @@ -40,7 +50,7 @@ skuilder init physics-101 \ --no-interactive ``` -### Dynamic data layer with CouchDB +#### Dynamic data layer with CouchDB ```bash skuilder init biology-course \ @@ -50,7 +60,7 @@ skuilder init biology-course \ --theme=medical ``` -## Command Options +#### Command Options - `--data-layer ` - Choose data layer: `static` or `dynamic` (default: dynamic) - `--theme ` - Select theme: `default`, `medical`, `educational`, or `corporate` (default: default) @@ -58,6 +68,105 @@ skuilder init biology-course \ - `--couchdb-url ` - CouchDB server URL (required for dynamic data layer) - `--course-id ` - Course ID to import from CouchDB (optional) +### Studio Mode (Content Editing) + +Studio mode provides a complete visual editing environment for static courses: + +```bash +skuilder studio # Launch in current directory +skuilder studio ./my-course # Launch against specific packed course directory +skuilder studio --port 6000 # Use custom CouchDB port +skuilder studio --no-browser # Don't auto-open browser +``` + +#### What Studio Mode Does + +Studio mode creates a full editing environment by starting multiple services: + +1. **CouchDB Instance** (Docker container on port 5985+) + - Temporary database for editing course content + - Automatically loads your static course data + +2. **Express API Server** (port 3001+) + - Handles database operations and file writes + - Provides REST API for the web editor + +3. **Studio Web Interface** (port 7174+) + - Visual course editor with Vue.js + - Create/edit cards, manage tags, bulk import + - Live preview of changes + +#### Studio Workflow + +1. **Load Course Data**: Unpacks your `public/static-courses/` JSON files into temporary CouchDB +2. **Visual Editing**: Use the web interface to modify course content +3. **Save Changes**: Click "Flush to Static" to write changes back to your course files +4. **Important**: Studio mode **overwrites** your source files - backup before major edits + +#### Requirements + +- **Docker**: Required for CouchDB instance +- **Static Course Project**: Valid package.json with vue-skuilder dependencies +- **Course Data**: Existing content in `public/static-courses/` directory + +#### Studio Mode vs Regular Development + +| Feature | Regular Dev (`npm run dev`) | Studio Mode (`skuilder studio`) | +|---------|----------------------------|--------------------------------| +| Purpose | View/test course | Edit course content | +| Data Source | Static JSON files | Temporary CouchDB + Web Editor | +| Editing | Manual JSON editing | Visual web interface | +| Services | Just Vite dev server | CouchDB + Express + Studio UI | +| File Changes | Manual | Automatic via "Flush to Static" | + +### Course Data Management + +#### Pack/Unpack Commands + +For advanced users working with CouchDB data: + +```bash +# Convert CouchDB course to static files +skuilder pack my-course-id \ + --server http://localhost:5984 \ + --username admin \ + --password secret \ + --output ./exported-course + +# Convert static files to CouchDB course +skuilder unpack ./course-data \ + --server http://localhost:5984 \ + --username admin \ + --password secret \ + --database coursedb-imported \ + --validate +``` + +**Pack Command Options:** +- `--server ` - CouchDB server URL (default: http://localhost:5984) +- `--username ` - CouchDB username for authentication +- `--password ` - CouchDB password for authentication +- `--output ` - Output directory for static files (default: ./static-courses) +- `--chunk-size ` - Documents per chunk for large courses (default: 1000) +- `--no-attachments` - Skip downloading course attachments + +**Unpack Command Options:** +- `--server ` - CouchDB server URL (default: http://localhost:5984) +- `--username ` - CouchDB username for authentication +- `--password ` - CouchDB password for authentication +- `--database ` - Target database name (auto-generated if not provided) +- `--as ` - Custom name for the unpacked course +- `--chunk-size ` - Documents per batch upload (default: 100) +- `--validate` - Run migration validation after unpack +- `--cleanup-on-error` - Remove database if migration fails + +**Use Cases:** +- **Studio Mode Internal**: These commands power studio mode's load/save operations +- **Migration**: Move courses between static and dynamic deployments +- **Backup/Restore**: Export course data for safekeeping or transfer +- **CI/CD Workflows**: Automate course deployment and synchronization +- **Development**: Test with production course data locally + ## Generated Project Structure ``` @@ -138,8 +247,13 @@ node packages/cli/dist/cli.js init test-project ## Requirements -- Node.js 18.0.0 or higher -- npm or yarn package manager +### System Requirements + +- **Node.js 18.0.0 or higher** +- **npm or yarn package manager** +- **Docker** (required for studio mode only) + - Used to run temporary CouchDB instances + - Not needed for basic project creation or static course viewing ## Dependencies From 4bd2b627b98c0734c20b521878e4e5d8d4bf0b4a Mon Sep 17 00:00:00 2001 From: NiloCK Date: Fri, 4 Jul 2025 23:18:58 -0300 Subject: [PATCH 4/5] add: running thoughts on quilt.json spec --- agent/quiltDotJSON/a.1.assessment.md | 171 +++++++++++++++ .../a.2.quilt-dependency-assessment.md | 200 ++++++++++++++++++ 2 files changed, 371 insertions(+) create mode 100644 agent/quiltDotJSON/a.1.assessment.md create mode 100644 agent/quiltDotJSON/a.2.quilt-dependency-assessment.md diff --git a/agent/quiltDotJSON/a.1.assessment.md b/agent/quiltDotJSON/a.1.assessment.md new file mode 100644 index 000000000..94a424f39 --- /dev/null +++ b/agent/quiltDotJSON/a.1.assessment.md @@ -0,0 +1,171 @@ +# Assessment: skuilder.json Specification + +## Context + +The user wants to create a `skuilder.json` specification to formally define what constitutes a Skuilder project, similar to how `package.json` defines an npm package. + +## Current Project Analysis + +### Existing Structure + +The Vue Skuilder project currently uses `skuilder.config.json` with a basic structure: + +```json +{ + "title": "Project Name", + "dataLayerType": "static" | "couch", + "course": "courseId-uuid", + "couchdbUrl": "http://localhost:5984", + "theme": {...} +} +``` + +### Identified Gaps + +1. **Missing project metadata**: no version, author, description +2. **Fragmented configuration**: parameters scattered across different files +3. **Lack of validation**: no JSON schema for validation +4. **No dependency management**: Skuilder dependencies not specified +5. **Incomplete deployment configuration**: limited options + +## Proposed Options + +### Option 1: Minimal Extension +- Extend existing `skuilder.config.json` +- Add basic metadata and validation +- Minimal impact on existing projects + +**Advantages:** +- Simple migration +- Backward compatibility +- Minimal changes + +**Disadvantages:** +- Limited functionality +- No complete standardization + +### Option 2: Complete Specification +- Create a new complete `skuilder.json` specification +- Include all aspects: metadata, configuration, deployment +- Complete JSON schema with validation + +**Advantages:** +- Complete standardization +- Maximum flexibility +- Advanced tooling possible + +**Disadvantages:** +- Migration required for existing projects +- Increased complexity + +### Option 3: Hybrid Approach +- Maintain `skuilder.config.json` for compatibility +- Introduce optional `skuilder.json` with advanced features +- Progressive migration + +**Advantages:** +- Smooth transition +- User choice +- Controlled evolution + +**Disadvantages:** +- Two formats to maintain +- Potential confusion + +## Unique Features to Specify + +### 1. Course System +- Supported question types +- Learning data structure +- Educational metadata + +### 2. Dual Data Layer +- Static vs dynamic configuration +- CouchDB parameters +- Synchronization + +### 3. Educational Themes +- Business presets +- Visual customization +- Dark/light modes + +### 4. Studio Tools +- Edit mode configuration +- Development parameters +- Pack/unpack workflow + +### 5. Plugin Architecture +- Extensible question types +- Learning domains +- Custom components + +## Key Specification Elements + +### Proposed Structure + +```json +{ + "$schema": "https://schema.skuilder.org/project/v1.0.json", + "version": "1.0", + "project": { + "name": "string", + "title": "string", + "description": "string", + "version": "string", + "author": "string", + "license": "string" + }, + "skuilder": { + "version": "string", + "type": "standalone" | "platform", + "dataLayer": { + "type": "static" | "couch", + "static": {...}, + "couch": {...} + } + }, + "ui": { + "theme": {...}, + "branding": {...}, + "features": {...} + }, + "courses": { + "registry": "string", + "categories": ["string"], + "questionTypes": ["string"], + "dataShapes": ["string"] + }, + "build": {...}, + "development": {...}, + "deployment": {...}, + "scripts": {...} +} +``` + +### Benefits of this Approach + +1. **Standardization**: Consistent structure for all projects +2. **Validation**: JSON schema for automatic validation +3. **Tooling**: Auto-completion and validation in editors +4. **Flexibility**: Support for multiple configurations +5. **Scalability**: Versioning and automatic migration + +## Recommendation + +**I recommend Option 2: Complete Specification** for the following reasons: + +1. **Necessary standardization**: The project is mature enough to benefit from a complete specification +2. **Advanced tooling**: A complete specification enables more sophisticated CLI tools +3. **Ecosystem**: Facilitates template creation and integration with other tools +4. **Documentation**: The specification serves as living documentation of the framework +5. **Manageable migration**: The CLI can automate migration from `skuilder.config.json` + +### Recommended Next Steps + +1. **Define complete JSON schema** with validation +2. **Create templates** for different project types +3. **Implement migration** from current format +4. **Develop tooling** (validation, auto-completion) +5. **Document** the specification with examples + +This approach will position Vue Skuilder as a professional educational framework with clear standards and excellent developer experience. \ No newline at end of file diff --git a/agent/quiltDotJSON/a.2.quilt-dependency-assessment.md b/agent/quiltDotJSON/a.2.quilt-dependency-assessment.md new file mode 100644 index 000000000..c66c6aca4 --- /dev/null +++ b/agent/quiltDotJSON/a.2.quilt-dependency-assessment.md @@ -0,0 +1,200 @@ +# Assessment: Quilt-Based Content Dependency System + +## Context + +The goal is to create a `quilt.json` specification that enables educational content sharing and dependency management. This allows courses to depend on and reuse content from other courses without duplication, while maintaining clear interfaces for content consumption. + +## Use Case Example + +A Doomsday algorithm course needs modular arithmetic (mod 7) content. Instead of duplicating this content, it should be able to: +- Declare a dependency on a `math` quilt +- Specify it only needs the `mod7` subset +- Let the math course determine how to best serve that need + +## Core Architecture + +### ContentSource Interface Analysis + +From `@packages/db/src/core/interfaces/contentSource.ts`, the key interface is: + +```typescript +export interface StudyContentSource { + getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>; + getNewCards(n?: number): Promise; +} +``` + +### Proposed Quilt Structure + +```json +{ + "serviceDef": { + "name": "ContentSource", + "version": "1.0", + "adapter": "StaticDataLayerProvider" + }, + "metadata": { + "id": "math-core-v1", + "name": "Core Mathematics", + "version": "1.0.0", + "description": "Foundational math concepts", + "author": "...", + "license": "..." + }, + "provides": { + "skills": [ + { + "id": "modular-arithmetic", + "name": "Modular Arithmetic", + "subsets": ["mod7", "mod12", "general-modular"] + }, + { + "id": "basic-algebra", + "name": "Basic Algebra", + "subsets": ["linear-equations", "quadratic-equations"] + } + ] + }, + "dependencies": { + "requires": [ + { + "quilt": "arithmetic-basics", + "version": "^1.0.0", + "skills": ["addition", "subtraction", "multiplication"] + } + ], + "suggests": [ + { + "quilt": "number-theory", + "version": "^2.0.0", + "skills": ["prime-factorization"], + "reason": "Enhanced explanations for modular arithmetic" + } + ] + }, + "content": { + "source": { + "type": "static", + "path": "./courses/math-core" + }, + "index": { + "skills": { + "modular-arithmetic": { + "cards": ["mod-intro-001", "mod7-examples-001", "mod7-practice-001"], + "prerequisites": ["multiplication", "division-remainder"], + "difficulty": "intermediate" + } + } + } + } +} +``` + +## Key Components + +### 1. Service Definition +- **Interface compatibility**: Which ContentSource version this quilt implements +- **Adapter specification**: How the quilt's data gets consumed (StaticDataLayerProvider, CouchDataLayerProvider, etc.) + +### 2. Skill Taxonomy +- **Provides**: What educational skills/concepts this quilt offers +- **Subsets**: Granular divisions of skills for precise dependency management +- **Prerequisites**: Skills needed before accessing this content + +### 3. Dependency Management +- **Requires**: Hard dependencies on other quilts +- **Suggests**: Soft dependencies that enhance the experience +- **Version constraints**: Semantic versioning for compatibility + +### 4. Content Mapping +- **Source location**: Where the actual content lives +- **Skill indexing**: Maps skills to specific cards/content +- **Metadata**: Difficulty, prerequisites, learning objectives + +## Implementation Considerations + +### Content Discovery +```typescript +interface QuiltRegistry { + findQuiltsBySkill(skill: string): Promise; + resolveQuilt(id: string, version: string): Promise; + validateDependencies(quilt: QuiltDescriptor): Promise; +} +``` + +### Dependency Resolution +```typescript +interface DependencyResolver { + resolveSkillChain(requiredSkills: string[]): Promise; + buildStudySession(plan: ContentPlan, user: UserDBInterface): Promise; +} +``` + +### Content Filtering +```typescript +interface ContentFilter { + filterBySkills(source: StudyContentSource, skills: string[]): StudyContentSource; + filterByDifficulty(source: StudyContentSource, level: DifficultyLevel): StudyContentSource; + filterByPrerequisites(source: StudyContentSource, userSkills: string[]): StudyContentSource; +} +``` + +## Benefits + +### 1. Content Reusability +- Courses can share foundational content without duplication +- Specialized courses can focus on their unique value-add +- Consistent presentation of core concepts across the ecosystem + +### 2. Modular Architecture +- Clean separation of concerns +- Easier maintenance and updates +- Scalable content ecosystem + +### 3. Adaptive Learning +- Precise skill targeting +- Prerequisite enforcement +- Intelligent content recommendations + +### 4. Ecosystem Growth +- Lower barrier to creating specialized courses +- Encourages contribution to shared knowledge bases +- Natural evolution toward comprehensive curriculum coverage + +## Challenges + +### 1. Skill Taxonomy Standardization +- Need agreed-upon skill identifiers +- Difficulty levels must be consistent +- Prerequisite relationships need validation + +### 2. Content Quality Assurance +- Ensure dependencies provide quality content +- Version compatibility across skill updates +- Consistent learning experience across quilts + +### 3. Performance Implications +- Dependency resolution complexity +- Content loading from multiple sources +- Caching strategies for composed content + +## Recommendation + +This quilt-based approach addresses a real architectural need in educational content systems. It enables: + +1. **Composable curricula** where courses can be built from reusable skill-based components +2. **Efficient content creation** by leveraging existing, well-tested educational content +3. **Consistent learning experiences** through standardized skill taxonomies +4. **Scalable content ecosystems** that grow organically + +The proposed structure balances flexibility with standardization, providing clear interfaces while allowing for diverse content sources and presentation styles. + +### Next Steps + +1. **Define core skill taxonomy** for foundational subjects +2. **Implement dependency resolver** in the CLI +3. **Create quilt registry** for content discovery +4. **Build content filtering system** for subset selection +5. **Develop migration tools** to convert existing courses to quilts + +This approach transforms Vue Skuilder from a course platform into a composable educational content ecosystem. \ No newline at end of file From db1945963d023821d3b0a3745b7aceec4e3533c8 Mon Sep 17 00:00:00 2001 From: NiloCK Date: Sat, 5 Jul 2025 01:09:12 -0300 Subject: [PATCH 5/5] update readme --- readme.md | 119 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 80 insertions(+), 39 deletions(-) diff --git a/readme.md b/readme.md index 817e81a5a..8d9039a93 100644 --- a/readme.md +++ b/readme.md @@ -2,67 +2,108 @@ ![`standalone-ui` E2E](https://github.com/patched-network/vue-skuilder/actions/workflows/standalone-e2e-tests.yml/badge.svg) ![CLI Regression](https://github.com/patched-network/vue-skuilder/actions/workflows/cli-regression-test.yml/badge.svg) -General tooling for interactive tutoring systems, with experimentation toward +Modular toolkit for the construction of interactive tutoring systems, with experimentation toward - mass-collaborative authoring - mixture-of-expert-systems guided learning - self-healing courses via proactive surfacing of learning bottlenecks -- content inheritance between courses +- schema definition to share content between courses, e.g., a package manager for curricula +- MCP hooks for LLMs to responsibly generate structured content according to structured demand; slop on rails -Think: the FOSS lovechild of anki, duolingo, wikipedia, and MathAcadamy, with a more generalized surface area for the types of content and skills that can be exercised. +Think: the FOSS lovechild of Anki, Duolingo, Wikipedia, and MathAcademy, with a more generalized surface area for the types of content and skills that can be exercised. -Aiming toward effective libraries and a main learner-loop to enable: -- a. independent authoring of individual courses -- b. community developed courses -- c. a platform to support both a. and b. +## Quick Start -## Project Architecture - -This monorepo contains three top-level system components: - -- **Vue SPA Frontend** (`packages/platform-ui`): Vue 3 + Vuetify 3 progressive web app -- **Express API** (`packages/express`): Node.js backend API -- **CouchDB Database**: Storage layer with replication protocol support - -Which are in turn built from the helper packages: +### For Course Creators (building *with* `vue-skuilder`) (start here!) -- `common`: some core logic and interfaces that define communication between project components -- `common-ui`: UI components useful in both a `platform` and standalone `course` context -- `courses`: logic and interfaces for both generic and domain specific courses. -- `db`: interfaces for the application's communication with the data later, and an implementation for CouchDB backend via PouchDB +Install the Skuilder CLI to create your first course: -## Development Quick Start - -### Prerequisites +```bash +npm install -g skuilder # npx ok too! +skuilder init my-course --data-layer=static +cd my-course +npm run dev # serve your course locally +npm run studio # edit your course content via web UI +``` -- Node.js 18+ -- Yarn 4 (or corepack) -- Docker (for development database) +### For Platform Developers / Contributors (building `vue-skuilder` itself) -### Commands +Clone and develop the full platform: ```bash git clone https://github.com/patched-network/vue-skuilder.git cd vue-skuilder -git submodule update --init --recursive # a test-time database dump yarn install -yarn dev +yarn setup # makes git submodule available - test database +yarn dev # runs platform-ui, express API, and CouchDB ``` -`dev` here: -- Builds packages -- Starts a local CouchDB instance in Docker with test data (http://localhost:5984) -- Launches the Express backend server (http://localhost:3000) -- Launches the Vue frontend (http://localhost:5173) +## Project Architecture -## Production Build +This monorepo is structured to support both **platform development** and **course creation**. -```bash -yarn build +Broadly: an education system has `User` and `Content` as endpoints, with `UI` as the mediating software in between. + +Here: + +### User + +The only user abstraction in the project is the `UserDBInterface`, which lives in the `@vue-skuilder/db` package. It's powered by PouchDB, which stores data locally in the case of static courses, or syncs with a CouchDB backend in dynamic / platform deployments. + +### Content + +Again, contained in the `db` package. Content is served over a core interface: + +``` +interface StudyContentSource { + getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>; + getNewCards(n?: number): Promise; +} ``` -This builds all packages and outputs the frontend as a static web app in the `packages/platform-ui/dist` folder and the backend in `packages/express/dist`. +Various implementations satisfy this interface, but the important distinction is that content can be either **static** (JSON files) or **dynamic** (CouchDB database). The `db` package contains converters to transform courses between these form factors as well, enabling, e.g., checkpointing and portable deployment of a 'live' course. + +### UI + +There are several UI *application* packages: +- `standalone-ui`: a skeleton static SPA for rendering a course. The thing that you'd deploy as user-facing. +- `studio-ui`: a focused content editor for individual courses, usable against either static or dynamic courses. +- `platform-ui`: ⚠️functional wip⚠️ a static SPA for managing many users and courses, allowing, e.g., multi-course study sessions, user course creation, classrooms (teacher-led cohorts). NB: the site itself is static, but it connects to a dynamic backend API and CouchDB database. +- `tuilder`: ⚠️**non**-functional wip⚠️ a tui for consuming courses in the terminal + +And some shared UI packages: +- `common-ui`: a library of reusable Vue components and utilities +- `courses`: a package containing domain-specific course logic and content types, also base-types for course content rendering components (e.g., a Chessboard component for a chess course) +- `edit-ui`: course editing widgets used in both `studio-ui` and `platform-ui` + +All web UI is built with Vue 3 and Vuetify 3, in TypeScript, mostly with Composition API and Pinia state management. All web UI shares most of its config via `./vite.config.base.json` + +### Glue + +The `express` backend API server is responsible, in dynamic-data contexts, for: +- post-processing media content +- enforcing correct metadata in course databases +- handling various user requests +- and probably other stuff as well! + +The `common` package contains some core logic and interfaces that define communication between components. + +### Utility + +The `cli` package (published on npm as `skuilder`) gives commands to create, manage, or migrate courses. See [packages/cli/README.md](packages/cli/README.md) for more details. + +## 🤝 Contributing + +Please do: +- kick tires +- file issues (bugs) +- file issues (questions) +- file issues (feature requests, roadmap / vision discussions) +- open smallish PRs that present as clear wins, even without prior discussion + +Probably don't: +- open large PRs without prior discussion -## License +## 📄 License This project is licensed under: