Learning Module Specification

Purpose

The learning module implements the Learning Domain inside the Spring Boot Modulith. It owns Algosure Academy content, course catalogues, learning paths, lessons, quizzes, practical exercises, certificates, user progress, organization learning profiles, procurement maturity assessments, knowledge gaps, learning recommendations, and learning-side AI tutor session records.

Owned Domain

Learning owns education state, learning records, progress, certificates, maturity education state, and recommendations. It references Organization, Identity, Intelligence, Opportunity, Compliance, Bid, and Contract records but does not own their source facts or reasoning sessions.

Owned Aggregates

Aggregate	Responsibility
Learning Catalog	Published course, module, lesson, quiz, and practical exercise structure.
Learning Path	Ordered learning journeys for user segment, organization maturity level, or procurement goal.
User Progress	Enrollments, lesson completion, quiz attempts, submissions, certificate eligibility, and progress status.
Organization Learning Profile	Organization-level education maturity, progress summaries, knowledge gaps, and recommended outcomes.
Procurement Maturity Assessment	Assessment questions, responses, scoring, maturity level, and knowledge gaps.
Certificate	Certificate issue date, recipient, course/path version, status, and revocation state.
Learning Recommendation	Recommended learning actions, reason, lifecycle, target asset, and priority.
AI Tutor Session Record	Learning-side tutor session record, references, confidence, guardrail result, and learning impact.

Owned Entities

Course, Module, Lesson, Video Lesson, Interactive Lesson, Quiz, Quiz Attempt, Practical Exercise, Exercise Submission, Certificate, Learning Path, User Progress, Organization Learning Profile, Procurement Maturity Assessment, Knowledge Gap, Learning Recommendation, and AI Tutor Session.

Owned Value Objects

CourseId, ModuleId, LessonId, LearningAssetId, ContentType, DifficultyLevel, LearningStatus, ProgressPercentage, QuizScore, PassThreshold, CertificateStatus, MaturityLevel, KnowledgeGapSeverity, RecommendationPriority, TutorSessionStatus, AIConfidenceScore, RubricVersion, OrganizationId reference, and UserId reference.

Commands

Command	Responsibility
PublishCourse	Publish approved course structure and version.
CreateLearningPath	Create ordered path toward a learning goal.
EnrollUser	Enrol user into course or path.
StartLesson	Record lesson start.
CompleteLesson	Record lesson completion according to rules.
SubmitQuizAttempt	Score and record quiz attempt.
SubmitPracticalExercise	Record applied exercise submission.
EvaluateCertificate	Check completion criteria and issue certificate where allowed.
RevokeCertificate	Revoke certificate with audit reason.
CompleteProcurementMaturityAssessment	Score maturity assessment and identify gaps.
IdentifyKnowledgeGap	Create or update knowledge gap from learning or cross-domain evidence.
CreateLearningRecommendation	Recommend course, lesson, exercise, or path.
StartAITutorSession	Start guarded tutor support session.
CompleteAITutorSession	Record tutor summary, confidence, and guardrail outcome.
UpdateOrganizationLearningProfile	Update organization education state from learning facts.

Queries

Query	Responsibility
GetCourseCatalog	Return published courses, modules, lessons, quizzes, and exercises.
GetLearningPath	Return ordered learning path and goal.
GetUserEnrollments	Return user enrollments and status.
GetLesson	Return lesson content metadata and completion rules.
GetQuiz	Return quiz metadata and attempt rules.
GetUserProgress	Return user progress by asset.
GetCertificates	Return certificate records where authorized.
GetOrganizationLearningProfile	Return organization maturity and education state.
GetProcurementMaturityAssessment	Return assessment result and rubric version.
GetKnowledgeGaps	Return gaps, severity, and evidence references.
GetLearningRecommendations	Return recommended learning actions and reasons.
GetAITutorSession	Return tutor session record and guardrail outcome.

Application Services

CourseCatalogApplicationService, LearningPathApplicationService, EnrollmentApplicationService, LessonProgressApplicationService, QuizApplicationService, PracticalExerciseApplicationService, CertificateApplicationService, ProcurementMaturityApplicationService, KnowledgeGapApplicationService, LearningRecommendationApplicationService, AITutorApplicationService, and OrganizationLearningProfileApplicationService.

Domain Services

CoursePublicationService, EnrollmentService, ProgressTrackingService, QuizScoringService, PracticalExerciseReviewService, CertificateIssuanceService, ProcurementMaturityAssessmentService, KnowledgeGapService, LearningRecommendationService, AITutorSafetyService, and CrossDomainTriggerService.

Policies

Course Publication Policy, Enrollment Policy, Progress Tracking Policy, Quiz Scoring Policy, Practical Exercise Review Policy, Certificate Issuance Policy, Procurement Maturity Assessment Policy, Knowledge Gap Policy, Learning Recommendation Policy, AI Tutor Safety Policy, and Cross-Domain Trigger Policy.

Repositories

CourseRepository, ModuleRepository, LessonRepository, QuizRepository, PracticalExerciseRepository, CertificateRepository, LearningPathRepository, UserProgressRepository, OrganizationLearningProfileRepository, ProcurementMaturityAssessmentRepository, KnowledgeGapRepository, LearningRecommendationRepository, AITutorSessionRepository, and LearningAuditRepository.

Events Published

CoursePublished, LearningPathCreated, UserEnrolled, LessonStarted, LessonCompleted, QuizAttemptSubmitted, PracticalExerciseSubmitted, CertificateIssued, ProcurementMaturityAssessmentCompleted, KnowledgeGapIdentified, LearningRecommendationCreated, AITutorSessionStarted, AITutorSessionCompleted, OrganizationLearningProfileUpdated, and UserProgressUpdated.

Events Consumed

OrganizationProfileUpdated, ComplianceRiskIdentified, ProcurementReadinessScoreUpdated, BidOutcomeCaptured, LessonsLearnedCaptured, ContractLessonsLearnedCaptured, TenderSaved, BidNoBidRecommendationCreated, AIRecommendationProduced, MfaChallengeRequired, and AdministrativePolicyChanged.

REST API Responsibility

The module owns API responsibilities for course catalogues, learning paths, enrollments, lessons, quizzes, practical exercises, certificates, user progress, procurement maturity assessments, recommendations, AI tutor sessions, and organization learning profiles. Final endpoint specs are deferred.

Database Ownership

Learning owns conceptual persistence for courses, modules, lessons, video lessons, interactive lessons, quizzes, quiz attempts, practical exercises, submissions, certificates, learning paths, path steps, user progress, organization learning profiles, maturity assessments, knowledge gaps, recommendations, AI tutor sessions, and learning audit logs.

Module Dependencies

Allowed dependencies are shared kernel identifiers, identity user and authorization context, organization profile references, intelligence tutor reasoning and explanation boundaries, opportunity, compliance, bid, and contract learning triggers, notification recommendation and certificate triggers, and analytics education projections.

Forbidden Dependencies

Learning must not mutate Organization profile facts, Compliance evidence, Opportunity records, Bid workspaces, Contract delivery facts, Intelligence reasoning sessions, Notification delivery records, or Analytics projections. Adjacent domains must not issue certificates or mutate progress directly.

AIOS Interaction Boundary

AIOS may generate educational explanations, tutor responses, knowledge-gap context, and recommendation support through governed Learning application services. Learning owns tutor session records, guardrail outcomes, progress updates, recommendations, and certificate decisions.

Security And Tenant Rules

• Learning progress, certificates, maturity assessments, and tutor sessions are tenant-scoped and user-scoped.
• Course catalogue content may be platform-scoped, but enrollment and progress are organization-scoped.
• AI tutor output must be guarded against final legal, financial, tax, or compliance advice.
• Certificate issuance and revocation require audit context.
• Historical progress must remain tied to content version and rubric version.

Test Strategy

Tests must cover course publication, enrollment, progress tracking, quiz scoring, exercise submission, certificate issuance and revocation, maturity assessment scoring, knowledge-gap creation, recommendation creation, AI tutor guardrails, event publication, idempotent event consumption, tenant filtering, authorization, and Spring Modulith boundary verification.

Future Microservice Extraction Notes

Learning can be extracted when Academy usage and tutor workflows require independent scaling. Extraction requires stable user and organization references, event contracts from adjacent domains, certificate retention rules, tutor integration contracts, and separation from Intelligence reasoning storage.

Mermaid Component Diagram

flowchart TD
    Api[learning.api.rest]
    App[learning.application.service]
    Command[learning.application.command]
    Query[learning.application.query]
    Domain[learning.domain.model]
    Policy[learning.domain.policy]
    Repo[learning.infrastructure.persistence]
    Messaging[learning.infrastructure.messaging]
    Identity[identity user context]
    Organization[organization context]
    Intelligence[intelligence tutor support]
    Compliance[compliance triggers]
    Bid[bid learning triggers]
    Contract[contract lessons]
    Notification[notification triggers]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Messaging
    App --> Identity
    App --> Organization
    App --> Intelligence
    App --> Compliance
    App --> Bid
    App --> Contract
    Messaging --> Notification