Docs Type Safety

Type Safety Documentation Audit & Update

Audit every file in _docs/type/ against the live codebase and fix any errors, gaps, or stale information so the docs are the authoritative single source of truth for the 7-layer type safety chain.

Type Safety Chain: Error Check and Fix (reference)

When running or documenting validation, use this workflow. Full detail lives in _docs/type/TYPE_SAFETY.md (Error Fixing Protocol).

Run error check

1. Full chain: npx tsc --noEmit -p tsconfig.build.json — checks all layers (server + client + shared schema).
2. Client only: npx tsc --noEmit (uses tsconfig.json, covers src/ only).
3. Exit 0 = success (no type errors). Non-zero = failure with errors printed to stdout.

Fix errors (until 0 errors)

1. Run npx tsc --noEmit -p tsconfig.build.json.
2. If errors appear, trace each error to its source layer (fix at the lowest layer possible — never change a lower layer to satisfy an upper one). See _docs/type/TYPE_SAFETY.md "Error Fixing Protocol" and the layer doc in _docs/type/layers/ for guidance.
3. Re-run type check after fixes.
4. Repeat until exit 0.

Layer-specific fix hints

Before Starting

1. Read every file in _docs/type/ (README.md, TYPE_SAFETY.md, all files in layers/).
2. Gather ground truth from the codebase for each layer — use the actual source files as the authority.

Ground Truth Collection

For each layer, collect the following from the actual codebase (not from existing docs):

Layer 1 — Drizzle Schema

• Read shared/alan-hirsch/database/schema.ts (structure, key table exports)
• Identify tables used by Content Studio: contentItems, courseLessons, courses, courseModules, comments, mediaItems
• Note helper functions: id(), createdAt(), updatedAt()

Layer 2 — Server Routes

• List server/routes/*.routes.ts files
• For each route file, note: base path, HTTP methods, which DB tables are queried, which mappers are used
• Check for tenant isolation (organization_id filtering)
• Current files: articles, courses, lessons, media, comments, video-projects, ai, auth

Layer 3 — Mappers

• List server/mappers/*.mapper.ts files
• For each mapper, note: Row interface, frontend type, toStudio*/fromStudio* exports, JSONB field handling
• Current files: article, course, lesson, media, video-project

Layer 4 — Frontend Types

• Read src/types.ts for core types (ContentType, WorkflowStatus, Lesson, Module, Course, CourseMetadata, MediaAsset, etc.)
• Read src/types/video-editor.ts for video domain types (Scene, Track, VideoFormat, VideoCompositionProps, etc.)

Layer 5 — API Client

• Read src/api/client.ts for apiFetch<T> signature, auth handling, error handling, 204 behavior

Layer 6 — React Hooks

• List src/hooks/*.ts files
• For each hook file, note: query keys, endpoints, return types, invalidation patterns
• Note useVideoProject custom hook with debounced auto-save pattern
• Current files: useArticles, useCourses, useLessons, useMedia, useComments, useVideoProject, useAuth

Layer 7 — UI Components

• Sample key components in src/components/ and src/components/video-editor/
• Note which hooks and types each component imports
• Current key components: Editor, CourseSettings, VideoStudio, MediaLibrary, AIAgent, Teleprompter, VideoEditorShell, SceneInspector, StoryboardView

Cross-Cutting

• Read tsconfig.json, tsconfig.build.json, tsconfig.server.json for include/exclude patterns
• Read server/db.ts for database connection pattern
• Verify getTenantOrgId() usage for tenant isolation

Audit Checklist

Compare every claim in the docs against ground truth. Flag and fix:

1. Incorrect counts — table counts, entity counts, file counts
2. Wrong patterns — code examples that don't match actual generated code
3. Missing information — new files, types, or conventions not documented
4. Stale references — files, paths, or commands that no longer exist
5. Naming convention errors — incorrect camelCase/PascalCase/kebab-case mappings
6. JSONB field contents — verify what each JSONB column actually stores
7. Type union values — verify ContentType, WorkflowStatus, VideoFormat, etc. match actual code
8. Commands — ensure all pnpm/npx commands listed match what actually works
9. Cross-references — ensure layer docs reference each other correctly
10. Video editor chain — verify video-project.mapper.ts ↔ video-editor.ts ↔ useVideoProject ↔ VideoEditorShell chain is documented

Update Rules

• Fix errors in place — do not create new files unless a section genuinely needs its own file
• Use actual code snippets from the codebase, not invented examples
• Keep the same document structure and voice — just make it accurate
• Update counts, paths, patterns, and examples to match reality
• If a doc file covers something that no longer exists, remove that section
• If the codebase has something undocumented, add it to the appropriate doc
• Update the README.md index if any files were added or removed

After Updating

1. Review each updated file for internal consistency
2. Ensure no doc references a pattern that contradicts another doc
3. Verify all code examples are syntactically correct
4. Confirm the README.md index accurately lists all files in _docs/type/
5. Run npx tsc --noEmit -p tsconfig.build.json to confirm type safety passes