New_Micro_Learning/docs/screen-architecture.md

Screen Architecture

Screens orchestrate reusable components and route-level data boundaries. They do not own domain logic or duplicate server state.

Workspaces

• /admin: SaaS operations and platform health
• /app: Course Designer creative and monitoring workspace
• /manager: authorized team analytics
• /learn: mobile-first assigned learning

Designer navigation includes /app/skills-taxonomy and Monitoring > Skills & Competencies. Contextual LearningMappingPanel is reused for Course, Module, Lesson, Block, Question, and Assessment.

Every meaningful route renders loading, empty, populated, error, and permission-denied states. Offline state is explicit where supported. Mutations expose pending, success, and failure.

Desktop uses persistent workspace navigation. Tablet uses collapsible panels. Designer mobile uses a drawer; the full Builder is not compressed into an unusable layout. Learner mobile uses at most five labeled bottom-navigation destinations.

Course Builder

• Real route: /app/courses/:courseId/versions/:versionId/lessons/:lessonId/builder
• UI-review route: /app/builder-preview (clearly labelled local-only sample data)
• Physical desktop layout: block library, canvas, contextual inspector, and course structure; content inside each panel follows the active document direction.
• TanStack Query owns server documents and mutations. Zustand owns selection, panel, and device-preview state only.
• DnD is progressive enhancement: every library block has a semantic button for click/keyboard insertion and canvas handles have accessible labels.
• Inspector edits are debounced before the API mutation. The server remains authoritative through expectedRevision; conflict responses are HTTP 409 and include the current block.
• Widths below 760px show a clear larger-screen requirement instead of a misleading compressed authoring surface.