Physician Course Preview Builder

Overview

This skill creates JSON-based lectures for the physician course preview system. Lectures are rendered using the UniversalLecture component and are accessible via unlisted URLs for physician feedback before publication.

System Architecture

content/
└── physician-courses/
    ├── registry.ts                    # Central registry (import lectures here)
    └── [physician-slug]/
        └── [course-slug]/
            └── lecture-N.json         # Individual lecture files

src/views/preview/
├── CourseCatalog.tsx                  # /preview/courses
├── PhysicianCourseIndex.tsx          # /preview/courses/:physician
└── PhysicianLectureViewer.tsx        # /preview/courses/:physician/:lectureSlug

URL Structure

• Catalog: /preview/courses
• Physician Index: /preview/courses/{physician-id}
• Lecture View: /preview/courses/{physician-id}/{course-id}-{lecture-number}

Example: /preview/courses/dr-abid-husain/new-biology-vascular-1

Creating a New Lecture

Step 1: Create the Lecture JSON File

Location: content/physician-courses/{physician-slug}/{course-slug}/lecture-N.json

Use the JSON schema from content/lectures/schema.ts. Required fields:

{
  "id": "course-slug-N",
  "title": "Lecture Title",
  "module": "Course Name",
  "duration": 45,
  "lastUpdated": "YYYY-MM-DD",
  "description": "Brief description",
  "level": "Foundational|Intermediate|Advanced",
  "tags": ["Tag1", "Tag2"],
  "slides": [...],
  "keyTakeaways": [...],
  "references": [...]
}

Step 2: Register in registry.ts

Add the import and register the lecture:

// Import at top of file
import drNewPhysicianLecture1 from './dr-new-physician/course-slug/lecture-1.json';

// Add to physicianRegistry
export const physicianRegistry: Record<string, PhysicianRegistry> = {
  'dr-new-physician': {
    physician: {
      id: 'dr-new-physician',
      name: 'Dr. New Physician',
      credentials: 'MD',
      specialty: 'Specialty Area',
    },
    courses: [
      {
        id: 'course-slug',
        title: 'Course Title',
        description: 'Course description',
        status: 'preview',
        lectures: [
          {
            id: 'lecture-1',
            title: 'Lecture Title',
            order: 1,
            lecture: drNewPhysicianLecture1 as Lecture,
          },
        ],
      },
    ],
  },
};

Slide Structure

Each slide supports:

Content Blocks (10 types)

• paragraph - Text paragraph
• bullets - Bullet list
• numbered - Numbered list
• definition - Term and definition
• quote - Quote with attribution
• caseStudy - Clinical case (scenario, approach, outcome)
• formula - Mathematical formula
• comparisonText - Side-by-side comparison items
• highlight - Highlighted text box
• table - Data table with headers and rows

Callouts (5 types)

• clinicalNote - Clinical guidance
• keyTakeaway - Key point summary
• evidence - Research evidence (study + finding)
• warning - Important warnings
• proTip - Practical tips

Diagrams (20 types)

Common types: pathway, comparison, process, network, hierarchy, timeline, matrix, beforeAfter

IMPORTANT - Network Diagrams: Use edges (not links):

IMPORTANT - Hierarchy Diagrams: Nodes only have label, color, children - NO id field:

{
  "type": "hierarchy",
  "title": "Diagram Title",
  "root": {
    "label": "Root Node",
    "color": "gold",
    "children": [
      { "label": "Child 1", "color": "blue" },
      { "label": "Child 2", "color": "green" }
    ]
  }
}

Network Diagram Example:

{
  "type": "network",
  "nodes": [...],
  "edges": [
    { "from": "node1", "to": "node2", "type": "unidirectional" }
  ]
}

IMPORTANT - QuadrantDiagram:

• Item text renders as WHITE on dark quadrant backgrounds
• Keep item names concise (1-3 words recommended)
• Example: "CoQ10", "BH4", "Beetroot" (good) vs "Coenzyme Q10 supplement" (too long)

IMPORTANT - NetworkDiagram Labels:

• Labels ≤10 characters: displayed INSIDE the node circle
• Labels >10 characters: displayed BELOW the node circle
• Keep labels concise for best visual appearance
• Example: "Gut", "Liver" (good) vs "Blood Vessel" (will render below circle)

Coding Guidelines

CRITICAL: Avoid Nested Anchor Tags

When using wouter's <Link> component, DO NOT nest <a> tags inside:

// WRONG - causes hydration errors
<Link href="/path">
  <a className="...">Content</a>
</Link>

// CORRECT - pass props directly to Link
<Link
  href="/path"
  className="..."
  style={{...}}
>
  Content
</Link>

CRITICAL: React Keys for List Rendering

Always provide unique, stable keys when rendering lists. Keys must be unique among siblings.

// WRONG - missing key or using undefined property
{items.map((item) => (
  <div key={item.id}>{item.label}</div>  // If 'id' doesn't exist in schema!
))}

// CORRECT - use existing properties with index for uniqueness
{items.map((item, index) => (
  <div key={`${item.label}-${index}`}>{item.label}</div>
))}

// CORRECT - for hierarchical/nested data, include level for uniqueness
{node.children.map((child, index) => (
  <div key={`${child.label}-${level}-${index}`}>
    {renderNode(child, level + 1, index)}
  </div>
))}

Key Points:

• Schema types may not have id fields - check content/lectures/schema.ts
• For hierarchy diagrams: nodes only have label, color, children - NO id field
• Use label + level + index combination for unique keys in recursive structures
• Never assume a property exists - verify against the actual schema

Component Patterns

For clickable cards/buttons:

<Link
  href={`/preview/courses/${physicianId}/${lectureSlug}`}
  className="block p-6 rounded-lg transition-all hover:shadow-md"
  style={{ backgroundColor: colors.paperAlt }}
>
  <div>Card content here</div>
</Link>

Workflow

1. Create lecture JSON in the physician's course folder
2. Register in content/physician-courses/registry.ts
3. Test at /preview/courses/{physician}/{course-id}-{number}
4. Iterate based on physician feedback
5. Publish by changing status to published

Example Lecture JSON

See content/physician-courses/dr-abid-husain/new-biology-vascular/lecture-1.json for a complete example.

Schema Reference

Full TypeScript types are in content/lectures/schema.ts:

• Lecture - Top-level lecture structure
• Slide - Individual slide with content, diagram, callouts
• ContentBlock - 10 content block types
• Callout - 5 callout types
• Diagram - 20 diagram types