New_Micro_Learning/docs/architecture.md

Architecture

Product boundary

This is an authoring-first microlearning platform, not a conventional LMS. The canonical course model serves Builder, Preview, Player, SCORM, PDF, and MP4 renderers. Learning intelligence adds structured, explainable links from content to evidence and capability without treating learning evidence as employee performance evaluation.

System shape

React/PWA -> Laravel JSON API -> Application commands/queries -> Domain modules
                                      |                       |
                                      v                       v
                                queues/events           MySQL/object storage
                                      |
                                      v
Evidence -> Capability -> Gaps/Coverage -> Insights -> Attention

Development, tests, and production use MySQL 8.4. Production also uses Redis-compatible cache/queues, S3-compatible object storage, and a WebSocket adapter.

Backend modules

• Identity, Tenancy, Organizations, Subscriptions
• Courses, Builder, Blocks, Assessments, Assignments, Learning Paths
• Learning Delivery, Events, Analytics, Monitoring, Attention
• Taxonomy, Content Mapping, Evidence, Capability, Coverage
• Collaboration, AI, Export, Notifications, Audit, System

Controllers translate HTTP only. Application services coordinate use cases. Domain objects own invariants. Infrastructure adapters implement persistence and external providers.

Frontend modules

Route-level modules are split by workspace (admin, designer, manager, learner) and feature. TanStack Query owns server state. Zustand is limited to complex UI state such as Builder selection, history, panels, preview, and drag state.

Tenancy

Authenticated organization context is established server-side. Client-provided organization identifiers never override it. Tenant scope applies to queries, commands, policies, jobs, events, exports, storage paths, and aggregates. Cross-tenant identifiers return not-found unless an explicitly authorized platform operation applies.

Deployment mode

DeploymentCapabilities exposes named capabilities for SAAS and ON_PREMISE. UI and domain code consume capabilities rather than scattering deployment-mode conditionals.

Learning intelligence pipeline

Learning Event -> Evidence Processor -> Evidence Record
 -> Capability Recalculation -> Snapshot -> Gap/Coverage Engines
 -> Insight -> Attention Action

Evidence is immutable and traceable. Score and confidence are separate. Scoring policies and algorithm versions are persisted. Published course mappings are immutable and evidence references the exact course version and mapping context.

Phases

0. Repository, architecture, ADRs, contracts, quality baseline
1. Design system and application shells
2. Authentication, tenancy, organization infrastructure
3. Users, teams, subscriptions, permissions A. Taxonomy core
4. Course domain and immutable versions B. Version-aware content mapping 5-6. Builder core and Block Registry
5. Assessments and scenarios C. Evidence generation 8-10. Publishing, assignments, player, PWA, manager workspace 11/D. Event pipeline, scoring and confidence E-F. Capability monitoring, gaps, and content coverage
6. Collaboration and realtime 13/G. AI and taxonomy assistance
7. Export Center and certificates
8. Production hardening and deployment

No phase advances while its quality gates are failing.