Digital Course Creation Guide: Engineering the Learning Asset Matrix

import { z } from 'zod';

// Base Asset Schema
const AssetSchema = z.object({
  id: z.string().uuid(),
  type: z.enum(['video', 'text', 'code', 'quiz', 'image']),
  version: z.string().semver(),
  metadata: z.object({
    title: z.string(),
    durationSeconds: z.number().optional(),
    tags: z.array(z.string()),
    accessibility: z.object({
      captionsUrl: z.string().url().optional(),
      transcript: z.string().optional(),
      altText: z.string().optional(),
    }),
  }),
});

// Learning Node Schema (Graph Vertex)
const LearningNodeSchema = z.object({
  id: z.string().uuid(),
  assetId: z.string().uuid(),
  prerequisites: z.array(z.string().uuid()), // References other Node IDs
  interactions: z.array(z.enum(['pause', 'quiz', 'checkpoint'])),
  timeEstimate: z.number(),
});

// Course Configuration Schema
const CourseSchema = z.object({
  id: z.string().uuid(),
  slug: z.string(),
  nodes: z.array(LearningNodeSchema),
  globalMetadata: z.object({
    difficulty: z.enum(['beginner', 'intermediate', 'advanced']),
    category: z.string(),
    lastUpdated: z.string().datetime(),
  }),
});

export type Course = z.infer<typeof CourseSchema>;
export type LearningNode = z.infer<typeof LearningNodeSchema>;

.

• Processing:
  • Video: Triggered via SQS to a transcoder (e.g., AWS MediaConvert) to generate HLS streams and thumbnails.
  • Code: Sanitized and stored for sandboxed execution.
  • Text: Processed for SEO and accessibility tags.
• Enrichment: Automated generation of transcripts (ASR) and embedding of accessibility metadata.
• Distribution: Assets are published to CDN edge nodes. The asset ID is immutable; updates create new versions.

3. Graph Rendering Engine

Courses are rendered by traversing the DAG of LearningNode objects. This allows for dynamic path resolution.

class CourseGraphEngine {
  private nodes: Map<string, LearningNode>;
  private completedNodes: Set<string>;

  constructor(course: Course, progress: string[]) {
    this.nodes = new Map(course.nodes.map(n => [n.id, n]));
    this.completedNodes = new Set(progress);
  }

  getNextNode(userId: string): LearningNode | null {
    // Find nodes where all prerequisites are met
    const available = Array.from(this.nodes.values()).filter(node => {
      if (this.completedNodes.has(node.id)) return false;
      return node.prerequisites.every(prereqId => 
        this.completedNodes.has(prereqId)
      );
    });

    // Return node with lowest time estimate for optimal path
    return available.sort((a, b) => a.timeEstimate - b.timeEstimate)[0] || null;
  }

  markComplete(nodeId: string): void {
    this.completedNodes.add(nodeId);
    // Trigger analytics event
    analytics.track('node_completed', { nodeId, userId });
  }
}

Architecture Decisions:

• Database: Use PostgreSQL for relational integrity of the graph structure and user progress. Use Redis for caching active course graphs.
• Storage: Object storage (S3/GCS) for binary assets. Never store binaries in the database.
• CDN: Configure Cache-Control headers based on asset versioning. Immutable assets can be cached indefinitely; versioned updates bust the cache automatically.

Pitfall Guide

1. The JSON Blob Trap: Storing entire course structures as a single JSON blob in the database.

   • Impact: Prevents granular updates, breaks caching strategies, and makes querying specific assets impossible.
   • Fix: Normalize the schema. Store nodes and assets separately, linking via foreign keys or references.

2. Ignoring Bandwidth Throttling: Serving raw video files without adaptive bitrate streaming (HLS/DASH).

   • Impact: High bounce rates on mobile networks; excessive CDN costs.
   • Fix: Implement multi-bitrate transcoding and client-side adaptive streaming.

3. Hardcoded Learning Paths: Embedding logic for prerequisites directly in the frontend code.

   • Impact: Inflexible curriculum; requires code deployment to change course flow.
   • Fix: Model dependencies in the data graph. The frontend should only render based on the graph state.

4. Missing Accessibility Metadata: Failing to associate captions and transcripts at the asset level.

   • Impact: Legal risk; exclusion of users with disabilities; poor SEO.
   • Fix: Make accessibility fields mandatory in the AssetSchema. Automate caption generation in the pipeline.

5. State Desynchronization: Allowing frontend progress tracking without server-side validation.

   • Impact: Users can cheat progress; analytics data is unreliable.
   • Fix: Implement server-side verification for node completion, especially for quizzes and checkpoints.

6. Over-Engineering the Player vs. Under-Engineering the Analytics: Focusing on UI polish while neglecting xAPI or custom event tracking.

   • Impact: Inability to measure learning outcomes or optimize content.
   • Fix: Define a comprehensive event schema (video_play, quiz_attempt, node_view) from day one.

7. Versioning Blindness: Updating assets without creating new versions.

   • Impact: Cache poisoning; users see broken content during updates; inability to rollback.
   • Fix: Enforce semantic versioning on all assets. URLs must include the version hash.

Production Bundle

Action Checklist

• Define Zod Schemas: Implement CourseSchema, AssetSchema, and LearningNodeSchema with strict validation rules.
• Setup Asset Pipeline: Configure S3 presigned uploads, SQS queues for transcoding jobs, and Lambda functions for metadata enrichment.
• Implement Graph Engine: Build the DAG traversal logic to resolve prerequisites and determine available nodes dynamically.
• Configure CDN Caching: Set Cache-Control: public, max-age=31536000, immutable for versioned assets; use version-based URLs.
• Add Accessibility Checks: Integrate automated caption generation and enforce altText/transcript presence in the upload flow.
• Deploy Analytics Events: Instrument the frontend to emit node_completed, quiz_score, and engagement events to the backend.
• Load Test Graph Resolution: Verify that the graph engine handles courses with 500+ nodes and complex dependency cycles without latency spikes.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small Niche Course (<50 Nodes)	Static Site Generator + JSON Config	Low overhead, fast deployment, minimal infra.	$
Enterprise LMS (10k+ Users)	Graph DB + Microservices	Scalability, complex permissions, real-time analytics.	$$$
Interactive Coding Platform	Sandboxed Execution Env + Asset Matrix	Security isolation, real-time code evaluation.	$$
Multi-Language Content	Structured Assets + Translation API	Text assets can be translated independently of video; reduces re-processing costs.	$$

Configuration Template

Use this template to initialize a course configuration in your system.

# course-config.yaml
course:
  id: "uuid-v4"
  slug: "advanced-typescript-patterns"
  metadata:
    title: "Advanced TypeScript Patterns"
    difficulty: "advanced"
    category: "development"
    
assets:
  - id: "asset-001"
    type: "video"
    source: "s3://bucket/intro.mp4"
    metadata:
      duration: 300
      captions: "s3://bucket/intro.vtt"
      
nodes:
  - id: "node-001"
    assetId: "asset-001"
    prerequisites: []
    interactions: ["checkpoint"]
    timeEstimate: 320
    
  - id: "node-002"
    assetId: "asset-002"
    prerequisites: ["node-001"]
    interactions: ["quiz"]
    timeEstimate: 600

Quick Start Guide

1. Initialize Project:

   npx create-codcompass-course@latest my-course-app
   cd my-course-app
   

2. Configure Environment: Set AWS_S3_BUCKET, DATABASE_URL, and CDN_ENDPOINT in .env.
3. Generate Schema: Run npm run generate:schema to create TypeScript types and database migrations based on the core models.
4. Upload Assets: Use the CLI to upload content:

   npm run upload:asset -- --type video --file ./lesson1.mp4 --title "Intro"
   

5. Deploy Graph: Push the course configuration to the API:

   npm run deploy:course -- --config ./course-config.yaml
   

   The system validates the graph, processes assets, and returns the live course URL within seconds.