Upload 39 files

.dockerignore

@@ -0,0 +1,11 @@
+.git
+.gitignore
+**/__pycache__
+**/.pytest_cache
+**/.mypy_cache
+**/.ruff_cache
+**/*.pyc
+**/*.pyo
+backend/.env
+backend/aididact.db
+backend/alembic/versions/*.pyc

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+WORKDIR /app
+
+COPY backend/requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir --upgrade pip && pip install --no-cache-dir -r /app/requirements.txt
+
+COPY backend /app
+
+EXPOSE 7860
+
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

README.md

@@ -1,12 +1,100 @@
----
-title: AIDidact
-emoji: 🏆
-colorFrom: red
-colorTo: indigo
-sdk: docker
-pinned: false
-license: mit
-short_description: AI-powered microlearning ecosystem built with FastAPI
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AIDidact
+
+AIDidact is a scalable AI-powered microlearning ecosystem for personalized, self-directed learning. The platform is organized around modular 5 ECTS learning units, hybrid recommendations, cheating-resistant assessments, and analytics-driven learner support.
+
+## Included Deliverables
+
+- [Architecture blueprint](C:\Users\user\Desktop\AI Flow\AIDidact\docs\architecture.md)
+- [Core algorithms](C:\Users\user\Desktop\AI Flow\AIDidact\docs\algorithms.md)
+- [Relational data schema](C:\Users\user\Desktop\AI Flow\AIDidact\schemas\schema.sql)
+- [REST API specification](C:\Users\user\Desktop\AI Flow\AIDidact\api\openapi.yaml)
+- [FastAPI backend scaffold](C:\Users\user\Desktop\AI Flow\AIDidact\backend\README.md)
+
+## System Overview
+
+AIDidact supports millions of learners across web and mobile channels. At registration, learners provide prior learning, goals, educational level, readiness signals, and optional learning preferences. That information is transformed into a learner profile vector used to personalize module recommendations, pacing, and feedback.
+
+Each microlearning module is worth 5 ECTS credits and includes Bloom-aligned objectives, chunked 10 to 15 minute content units, interactive activities, formative assessments, and explicit completion criteria. Modules are self-paced, measurable, and adaptive where possible.
+
+## Textual Architecture Diagram
+
+```mermaid
+flowchart LR
+    A["Web App"] --> G["API Gateway"]
+    B["Mobile App"] --> G
+    C["Admin Console"] --> G
+
+    G --> U["Auth and Consent Service"]
+    G --> P["Profile Service"]
+    G --> M["Module Service"]
+    G --> R["Recommendation Service"]
+    G --> S["Assessment Service"]
+    G --> T["Progress Service"]
+    G --> D["Dashboard Service"]
+
+    U --> PG["PostgreSQL"]
+    P --> PG
+    M --> PG
+    S --> PG
+    T --> PG
+
+    P --> K["Event Bus"]
+    M --> K
+    S --> K
+    T --> K
+
+    K --> L["Analytics Processor"]
+    L --> NS["NoSQL Log Store"]
+    L --> WH["Analytics Warehouse"]
+    L --> FS["Feature Store"]
+
+    R --> FS
+    R --> VX["Vector Index"]
+    R --> RM["Hybrid Recommender Models"]
+
+    S --> Q["Question Generation"]
+    S --> E["AI Evaluation"]
+    S --> I["Integrity Engine"]
+
+    D --> WH
+```
+
+## Key Design Decisions
+
+- Transactional data lives in PostgreSQL; high-volume telemetry flows to NoSQL and warehouse systems.
+- Recommendation uses hybrid content-based plus collaborative filtering and refreshes from learner progress.
+- Assessment uses blueprint-based randomized questions, AI-assisted open-ended grading, and anomaly detection.
+- GDPR compliance is built in through consent management, auditability, pseudonymization, retention rules, and human review paths.
+
+## Hugging Face Spaces
+
+This repository is now prepared for Hugging Face Spaces using `Docker`.
+
+Recommended Space setup:
+
+- SDK: `Docker`
+- Template: `Blank`
+- Hardware: `CPU Basic`
+
+For the easiest deployment path on Spaces:
+
+- use the included `Dockerfile`
+- keep `DATABASE_URL` as SQLite for demo use
+- optionally switch to an external PostgreSQL instance later via Space Secrets
+
+Main deployment files:
+
+- [Dockerfile](C:\Users\user\Desktop\AI Flow\AIDidact\Dockerfile)
+- [backend README](C:\Users\user\Desktop\AI Flow\AIDidact\backend\README.md)
+- [environment example](C:\Users\user\Desktop\AI Flow\AIDidact\backend\.env.example)
+
+## Example User Flow
+
+1. Learner registers and grants required consents.
+2. Diagnostic assessment establishes readiness and baseline mastery.
+3. Profile vector is generated from prior learning, goals, level, readiness, and preferences.
+4. Recommendation service ranks starter modules.
+5. Learner completes chunked units, activities, and formative checks.
+6. Events stream to analytics and update mastery, dashboards, and next recommendations.
+7. Learner completes a unique summative assessment with integrity controls.
+8. Module is marked complete only if score, engagement, and integrity thresholds are satisfied.

api/openapi.yaml

@@ -0,0 +1,433 @@
+openapi: 3.1.0
+info:
+  title: AIDidact API
+  version: 1.0.0
+  description: API contract for the AIDidact AI-powered microlearning ecosystem.
+servers:
+  - url: https://api.aididact.example.com
+paths:
+  /v1/auth/register:
+    post:
+      summary: Register a learner
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterLearnerRequest'
+      responses:
+        '201':
+          description: Registered
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LearnerRegistrationResponse'
+  /v1/learners/{learnerId}/profile:
+    get:
+      summary: Get learner profile
+      parameters:
+        - $ref: '#/components/parameters/LearnerId'
+      responses:
+        '200':
+          description: Learner profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LearnerProfile'
+    patch:
+      summary: Update learner goals or preferences
+      parameters:
+        - $ref: '#/components/parameters/LearnerId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateLearnerProfileRequest'
+      responses:
+        '200':
+          description: Updated
+  /v1/learners/{learnerId}/diagnostic-assessment:
+    post:
+      summary: Submit readiness assessment
+      parameters:
+        - $ref: '#/components/parameters/LearnerId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DiagnosticSubmission'
+      responses:
+        '202':
+          description: Accepted
+  /v1/modules:
+    get:
+      summary: List modules
+      responses:
+        '200':
+          description: Module list
+  /v1/modules/{moduleId}:
+    get:
+      summary: Get module detail
+      parameters:
+        - $ref: '#/components/parameters/ModuleId'
+      responses:
+        '200':
+          description: Module detail
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ModuleDetail'
+  /v1/learners/{learnerId}/recommendations:
+    get:
+      summary: Get ranked module recommendations
+      parameters:
+        - $ref: '#/components/parameters/LearnerId'
+      responses:
+        '200':
+          description: Recommendations
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/RecommendationItem'
+  /v1/enrollments:
+    post:
+      summary: Enroll learner in module
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [learnerId, moduleId]
+              properties:
+                learnerId:
+                  type: string
+                  format: uuid
+                moduleId:
+                  type: string
+                  format: uuid
+      responses:
+        '201':
+          description: Enrolled
+  /v1/interactions:
+    post:
+      summary: Ingest interaction event
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InteractionEvent'
+      responses:
+        '202':
+          description: Accepted
+  /v1/assessments/{assessmentId}/attempts:
+    post:
+      summary: Create unique assessment attempt
+      parameters:
+        - $ref: '#/components/parameters/AssessmentId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [learnerId]
+              properties:
+                learnerId:
+                  type: string
+                  format: uuid
+      responses:
+        '201':
+          description: Attempt created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssessmentAttempt'
+  /v1/assessments/attempts/{attemptId}/responses:
+    post:
+      summary: Submit responses
+      parameters:
+        - $ref: '#/components/parameters/AttemptId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssessmentResponseSubmission'
+      responses:
+        '202':
+          description: Accepted for grading
+  /v1/assessments/attempts/{attemptId}:
+    get:
+      summary: Get assessment result
+      parameters:
+        - $ref: '#/components/parameters/AttemptId'
+      responses:
+        '200':
+          description: Result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssessmentAttemptResult'
+  /v1/learners/{learnerId}/dashboard:
+    get:
+      summary: Get learner dashboard
+      parameters:
+        - $ref: '#/components/parameters/LearnerId'
+      responses:
+        '200':
+          description: Dashboard
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LearnerDashboard'
+components:
+  parameters:
+    LearnerId:
+      in: path
+      name: learnerId
+      required: true
+      schema:
+        type: string
+        format: uuid
+    ModuleId:
+      in: path
+      name: moduleId
+      required: true
+      schema:
+        type: string
+        format: uuid
+    AssessmentId:
+      in: path
+      name: assessmentId
+      required: true
+      schema:
+        type: string
+        format: uuid
+    AttemptId:
+      in: path
+      name: attemptId
+      required: true
+      schema:
+        type: string
+        format: uuid
+  schemas:
+    RegisterLearnerRequest:
+      type: object
+      required: [email, firstName, lastName, timezone, educationalLevel, goals, priorLearning]
+      properties:
+        email:
+          type: string
+          format: email
+        firstName:
+          type: string
+        lastName:
+          type: string
+        timezone:
+          type: string
+        educationalLevel:
+          type: string
+        priorLearning:
+          type: array
+          items:
+            $ref: '#/components/schemas/PriorLearningItem'
+        goals:
+          type: array
+          items:
+            $ref: '#/components/schemas/LearnerGoal'
+        preferences:
+          $ref: '#/components/schemas/LearnerPreferences'
+    LearnerRegistrationResponse:
+      type: object
+      properties:
+        learnerId:
+          type: string
+          format: uuid
+        nextStep:
+          type: string
+    PriorLearningItem:
+      type: object
+      properties:
+        learningType:
+          type: string
+          enum: [formal, non_formal, informal]
+        title:
+          type: string
+        provider:
+          type: string
+        description:
+          type: string
+    LearnerGoal:
+      type: object
+      properties:
+        goalHorizon:
+          type: string
+          enum: [short_term, long_term]
+        goalText:
+          type: string
+        targetDate:
+          type: string
+          format: date
+    LearnerPreferences:
+      type: object
+      properties:
+        preferredModalities:
+          type: array
+          items:
+            type: string
+        preferredSessionLengthMinutes:
+          type: integer
+    DiagnosticSubmission:
+      type: object
+      properties:
+        responses:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+    LearnerProfile:
+      type: object
+      properties:
+        learnerId:
+          type: string
+          format: uuid
+        readinessLevel:
+          type: string
+        readinessScore:
+          type: number
+        masteryMap:
+          type: object
+          additionalProperties: true
+    UpdateLearnerProfileRequest:
+      type: object
+      properties:
+        goals:
+          type: array
+          items:
+            $ref: '#/components/schemas/LearnerGoal'
+        preferences:
+          $ref: '#/components/schemas/LearnerPreferences'
+    ModuleDetail:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        title:
+          type: string
+        description:
+          type: string
+        objectives:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        units:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        completionCriteria:
+          type: object
+          additionalProperties: true
+    RecommendationItem:
+      type: object
+      properties:
+        moduleId:
+          type: string
+          format: uuid
+        rank:
+          type: integer
+        score:
+          type: number
+        reasons:
+          type: array
+          items:
+            type: string
+    InteractionEvent:
+      type: object
+      properties:
+        learnerId:
+          type: string
+          format: uuid
+        moduleId:
+          type: string
+          format: uuid
+        unitId:
+          type: string
+          format: uuid
+        activityId:
+          type: string
+          format: uuid
+        eventType:
+          type: string
+        eventTimestamp:
+          type: string
+          format: date-time
+        durationMs:
+          type: integer
+        payload:
+          type: object
+          additionalProperties: true
+    AssessmentAttempt:
+      type: object
+      properties:
+        attemptId:
+          type: string
+          format: uuid
+        assessmentId:
+          type: string
+          format: uuid
+        timeLimitMinutes:
+          type: integer
+        items:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+    AssessmentResponseSubmission:
+      type: object
+      properties:
+        responses:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+    AssessmentAttemptResult:
+      type: object
+      properties:
+        attemptId:
+          type: string
+          format: uuid
+        score:
+          type: number
+        passStatus:
+          type: string
+        integrityStatus:
+          type: string
+        humanReviewRequired:
+          type: boolean
+    LearnerDashboard:
+      type: object
+      properties:
+        learnerId:
+          type: string
+          format: uuid
+        timeOnTaskMinutes7d:
+          type: number
+        dropoutRisk:
+          type: number
+        successProbability:
+          type: number
+        adaptiveFeedback:
+          type: array
+          items:
+            type: string

backend/.env.example

@@ -0,0 +1,9 @@
+APP_NAME=AIDidact API
+APP_VERSION=0.1.0
+API_PREFIX=/v1
+ENVIRONMENT=development
+DEBUG=true
+DATABASE_URL=sqlite+aiosqlite:///./aididact.db
+SQL_ECHO=false
+AUTO_CREATE_TABLES=true
+APP_PORT=7860

backend/README.md

@@ -0,0 +1,85 @@
+# AIDidact FastAPI Backend
+
+This is a production-oriented FastAPI scaffold for the AIDidact microlearning platform. It now uses async SQLAlchemy with a PostgreSQL-first configuration, plus Alembic scaffolding for schema migrations.
+
+## Included
+
+- FastAPI app entrypoint
+- modular routers aligned with the platform domains
+- Pydantic request and response models
+- async SQLAlchemy models and repositories
+- Alembic migration scaffold
+- lightweight recommendation, profile, analytics, and assessment service logic
+- seeded demo modules and one summative assessment
+
+## Project Structure
+
+```text
+backend/
+  app/
+    api/
+    core/
+    db/
+    models/
+    services/
+    main.py
+  alembic/
+  alembic.ini
+  requirements.txt
+  pyproject.toml
+```
+
+## Run Locally
+
+1. Install Python 3.11 or newer.
+2. Create a virtual environment.
+3. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+4. Copy `.env.example` to `.env` and set `DATABASE_URL`.
+
+5. Run migrations:
+
+```bash
+alembic revision --autogenerate -m "initial schema"
+alembic upgrade head
+```
+
+For quick local development, `AUTO_CREATE_TABLES=true` will also create tables on startup.
+
+6. Start the API:
+
+```bash
+uvicorn app.main:app --reload
+```
+
+7. Open:
+
+- `http://127.0.0.1:8000/docs`
+- `http://127.0.0.1:8000/redoc`
+
+## Next Production Steps
+
+- add JWT authentication and consent middleware
+- connect recommendation features to a vector index and analytics feature store
+- introduce background workers for grading, anomaly detection, and recommendation refreshes
+- split module, assessment, and analytics domains into separate deployable services as traffic grows
+
+## Hugging Face Spaces
+
+For Hugging Face Spaces, choose:
+
+- `Docker`
+- `Blank`
+- `CPU Basic`
+
+Recommended first deployment setup:
+
+- keep `DATABASE_URL=sqlite+aiosqlite:///./aididact.db`
+- keep `AUTO_CREATE_TABLES=true`
+- do not run Alembic in the first demo deployment
+
+If you later use an external PostgreSQL database, add `DATABASE_URL` as a Hugging Face Space Secret and optionally disable automatic table creation after migrations are in place.

backend/alembic.ini

@@ -0,0 +1,36 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+sqlalchemy.url = postgresql+asyncpg://postgres:postgres@localhost:5432/aididact
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers = console
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s

backend/alembic/env.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from app.core.config import get_settings
+from app.db.base import Base
+from app.models import orm  # noqa: F401
+
+config = context.config
+settings = get_settings()
+config.set_main_option(
+    "sqlalchemy.url",
+    settings.database_url.replace("+asyncpg", "").replace("+aiosqlite", ""),
+)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True, compare_type=True)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from alembic import op
+import sqlalchemy as sa
+
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

backend/alembic/versions/.gitkeep

@@ -0,0 +1 @@
+

backend/app/__init__.py

@@ -0,0 +1 @@
+"""AIDidact FastAPI backend package."""

backend/app/api/__init__.py

@@ -0,0 +1 @@
+"""API router package."""

backend/app/api/deps.py

@@ -0,0 +1 @@
+from app.db.session import get_db_session

backend/app/api/router.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from app.api.routes import assessments, auth, learners, modules, progress, recommendations
+
+api_router = APIRouter()
+api_router.include_router(auth.router, prefix="/auth", tags=["Auth"])
+api_router.include_router(learners.router, prefix="/learners", tags=["Learners"])
+api_router.include_router(modules.router, prefix="/modules", tags=["Modules"])
+api_router.include_router(recommendations.router, prefix="/learners", tags=["Recommendations"])
+api_router.include_router(progress.router, tags=["Progress"])
+api_router.include_router(assessments.router, prefix="/assessments", tags=["Assessments"])

backend/app/api/routes/__init__.py

@@ -0,0 +1 @@
+"""Route modules for AIDidact."""

backend/app/api/routes/assessments.py

@@ -0,0 +1,46 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_db_session
+from app.models.schemas import (
+    AssessmentAttempt,
+    AssessmentAttemptCreate,
+    AssessmentAttemptResult,
+    AssessmentResponseSubmission,
+)
+from app.services import engines, repository
+
+router = APIRouter()
+
+
+@router.post("/{assessment_id}/attempts", response_model=AssessmentAttempt, status_code=status.HTTP_201_CREATED)
+async def create_attempt(
+    assessment_id: UUID,
+    payload: AssessmentAttemptCreate,
+    session: AsyncSession = Depends(get_db_session),
+) -> AssessmentAttempt:
+    await repository.get_learner(session, payload.learner_id)
+    assessment = await repository.get_assessment(session, assessment_id)
+    attempt = engines.generate_assessment_attempt(assessment, payload.learner_id)
+    return await repository.create_attempt(session, attempt)
+
+
+@router.post("/attempts/{attempt_id}/responses", status_code=status.HTTP_202_ACCEPTED)
+async def submit_responses(
+    attempt_id: UUID,
+    payload: AssessmentResponseSubmission,
+    session: AsyncSession = Depends(get_db_session),
+) -> dict[str, str]:
+    attempt = await repository.get_attempt(session, attempt_id)
+    result = engines.evaluate_attempt(attempt, len(payload.responses))
+    await repository.save_result(session, result)
+    return {"status": "accepted"}
+
+
+@router.get("/attempts/{attempt_id}", response_model=AssessmentAttemptResult)
+async def get_attempt_result(
+    attempt_id: UUID, session: AsyncSession = Depends(get_db_session)
+) -> AssessmentAttemptResult:
+    return await repository.get_result(session, attempt_id)

backend/app/api/routes/auth.py

@@ -0,0 +1,35 @@
+from fastapi import APIRouter, Depends, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_db_session
+from app.models.schemas import (
+    LearnerPreferences,
+    LearnerRecord,
+    LearnerRegistrationResponse,
+    RegisterLearnerRequest,
+)
+from app.services import engines, repository
+
+router = APIRouter()
+
+
+@router.post("/register", response_model=LearnerRegistrationResponse, status_code=status.HTTP_201_CREATED)
+async def register_learner(
+    payload: RegisterLearnerRequest, session: AsyncSession = Depends(get_db_session)
+) -> LearnerRegistrationResponse:
+    learner = LearnerRecord(
+        email=payload.email,
+        first_name=payload.first_name,
+        last_name=payload.last_name,
+        locale=payload.locale,
+        timezone=payload.timezone,
+        educational_level=payload.educational_level,
+        consent_personalization=payload.consent_personalization,
+        consent_analytics=payload.consent_analytics,
+        consent_version=payload.consent_version,
+        prior_learning=payload.prior_learning,
+        goals=payload.goals,
+        preferences=payload.preferences or LearnerPreferences(),
+    )
+    await repository.create_learner(session, engines.build_profile(learner))
+    return LearnerRegistrationResponse(learner_id=learner.id)

backend/app/api/routes/learners.py

@@ -0,0 +1,42 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_db_session
+from app.models.schemas import DiagnosticSubmission, LearnerProfile, UpdateLearnerProfileRequest
+from app.services import engines, repository
+
+router = APIRouter()
+
+
+@router.get("/{learner_id}/profile", response_model=LearnerProfile)
+async def get_profile(learner_id: UUID, session: AsyncSession = Depends(get_db_session)) -> LearnerProfile:
+    learner = await repository.get_learner(session, learner_id)
+    return engines.learner_to_profile(learner)
+
+
+@router.patch("/{learner_id}/profile", response_model=LearnerProfile)
+async def update_profile(
+    learner_id: UUID,
+    payload: UpdateLearnerProfileRequest,
+    session: AsyncSession = Depends(get_db_session),
+) -> LearnerProfile:
+    learner = await repository.get_learner(session, learner_id)
+    if payload.goals is not None:
+        learner.goals = payload.goals
+    if payload.preferences is not None:
+        learner.preferences = payload.preferences
+    await repository.update_learner(session, engines.build_profile(learner))
+    return engines.learner_to_profile(learner)
+
+
+@router.post("/{learner_id}/diagnostic-assessment", response_model=LearnerProfile)
+async def submit_diagnostic(
+    learner_id: UUID,
+    payload: DiagnosticSubmission,
+    session: AsyncSession = Depends(get_db_session),
+) -> LearnerProfile:
+    learner = await repository.get_learner(session, learner_id)
+    learner = await repository.update_learner(session, engines.build_profile(learner, payload))
+    return engines.learner_to_profile(learner)

backend/app/api/routes/modules.py

@@ -0,0 +1,20 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_db_session
+from app.models.schemas import ModuleDetail
+from app.services import repository
+
+router = APIRouter()
+
+
+@router.get("", response_model=list[ModuleDetail])
+async def list_modules(session: AsyncSession = Depends(get_db_session)) -> list[ModuleDetail]:
+    return await repository.list_modules(session)
+
+
+@router.get("/{module_id}", response_model=ModuleDetail)
+async def get_module(module_id: UUID, session: AsyncSession = Depends(get_db_session)) -> ModuleDetail:
+    return await repository.get_module(session, module_id)

backend/app/api/routes/progress.py

@@ -0,0 +1,45 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_db_session
+from app.models.schemas import Enrollment, EnrollmentCreate, InteractionEvent, LearnerDashboard, ProgressSummary
+from app.services import engines, repository
+
+router = APIRouter()
+
+
+@router.post("/enrollments", response_model=Enrollment, status_code=status.HTTP_201_CREATED)
+async def create_enrollment(
+    payload: EnrollmentCreate, session: AsyncSession = Depends(get_db_session)
+) -> Enrollment:
+    await repository.get_learner(session, payload.learner_id)
+    await repository.get_module(session, payload.module_id)
+    enrollment = Enrollment(learner_id=payload.learner_id, module_id=payload.module_id)
+    return await repository.create_enrollment(session, enrollment)
+
+
+@router.get("/learners/{learner_id}/progress", response_model=ProgressSummary)
+async def get_progress(
+    learner_id: UUID, session: AsyncSession = Depends(get_db_session)
+) -> ProgressSummary:
+    await repository.get_learner(session, learner_id)
+    return await engines.build_progress_summary(session, learner_id)
+
+
+@router.post("/interactions", status_code=status.HTTP_202_ACCEPTED)
+async def create_interaction(
+    payload: InteractionEvent, session: AsyncSession = Depends(get_db_session)
+) -> dict[str, str]:
+    await repository.get_learner(session, payload.learner_id)
+    await repository.create_interaction(session, payload)
+    return {"status": "accepted"}
+
+
+@router.get("/learners/{learner_id}/dashboard", response_model=LearnerDashboard)
+async def get_dashboard(
+    learner_id: UUID, session: AsyncSession = Depends(get_db_session)
+) -> LearnerDashboard:
+    learner = await repository.get_learner(session, learner_id)
+    return await engines.build_dashboard(session, learner)

backend/app/api/routes/recommendations.py

@@ -0,0 +1,19 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_db_session
+from app.models.schemas import RecommendationResponse
+from app.services import engines, repository
+
+router = APIRouter()
+
+
+@router.get("/{learner_id}/recommendations", response_model=RecommendationResponse)
+async def get_recommendations(
+    learner_id: UUID, session: AsyncSession = Depends(get_db_session)
+) -> RecommendationResponse:
+    learner = await repository.get_learner(session, learner_id)
+    modules = await repository.list_modules(session)
+    return engines.rank_modules(learner, modules)

backend/app/core/__init__.py

@@ -0,0 +1 @@
+"""Core configuration and shared utilities."""

backend/app/core/config.py

@@ -0,0 +1,28 @@
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    app_name: str = "AIDidact API"
+    app_version: str = "0.1.0"
+    api_prefix: str = "/v1"
+    environment: str = Field(default="development")
+    debug: bool = Field(default=True)
+    allowed_origins: list[str] = Field(default_factory=lambda: ["*"])
+    database_url: str = Field(default="sqlite+aiosqlite:///./aididact.db")
+    sql_echo: bool = Field(default=False)
+    auto_create_tables: bool = Field(default=True)
+    app_port: int = Field(default=7860)
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/app/db/__init__.py

@@ -0,0 +1 @@
+"""Storage backends for the AIDidact FastAPI scaffold."""

backend/app/db/base.py

@@ -0,0 +1,5 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass

backend/app/db/session.py

@@ -0,0 +1,32 @@
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.core.config import get_settings
+
+settings = get_settings()
+
+engine_kwargs: dict = {
+    "echo": settings.sql_echo,
+    "future": True,
+}
+
+if settings.database_url.startswith("sqlite+aiosqlite"):
+    engine_kwargs["connect_args"] = {"check_same_thread": False}
+
+engine = create_async_engine(
+    settings.database_url,
+    **engine_kwargs,
+)
+
+AsyncSessionLocal = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+    autoflush=False,
+)
+
+
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSessionLocal() as session:
+        yield session

backend/app/main.py

@@ -0,0 +1,47 @@
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.api.router import api_router
+from app.core.config import get_settings
+from app.db.base import Base
+from app.db.session import AsyncSessionLocal, engine
+from app.models import orm  # noqa: F401
+from app.services.bootstrap import seed_demo_data
+
+settings = get_settings()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    if settings.auto_create_tables:
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+    async with AsyncSessionLocal() as session:
+        await seed_demo_data(session)
+    yield
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    debug=settings.debug,
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/health")
+def healthcheck() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+app.include_router(api_router, prefix=settings.api_prefix)

backend/app/models/__init__.py

@@ -0,0 +1 @@
+"""Pydantic models used across the backend."""

backend/app/models/orm.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, Date, DateTime, Float, ForeignKey, Integer, JSON, String, Text, UniqueConstraint, Uuid, func
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db.base import Base
+
+
+class LearnerORM(Base):
+    __tablename__ = "learners"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
+    first_name: Mapped[str] = mapped_column(String(100), nullable=False)
+    last_name: Mapped[str] = mapped_column(String(100), nullable=False)
+    locale: Mapped[str] = mapped_column(String(20), default="en-US")
+    timezone: Mapped[str] = mapped_column(String(64), nullable=False)
+    educational_level: Mapped[str] = mapped_column(String(50), nullable=False)
+    consent_personalization: Mapped[bool] = mapped_column(Boolean, default=False)
+    consent_analytics: Mapped[bool] = mapped_column(Boolean, default=False)
+    consent_version: Mapped[str | None] = mapped_column(String(50))
+    readiness_level: Mapped[str] = mapped_column(String(30), default="unknown")
+    readiness_score: Mapped[float] = mapped_column(Float, default=0.0)
+    mastery_map: Mapped[dict] = mapped_column(JSON, default=dict)
+    risk_profile: Mapped[dict] = mapped_column(JSON, default=dict)
+    profile_vector: Mapped[list] = mapped_column(JSON, default=list)
+    preferences: Mapped[dict] = mapped_column(JSON, default=dict)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    prior_learning_items: Mapped[list["LearnerPriorLearningORM"]] = relationship(
+        back_populates="learner", cascade="all, delete-orphan"
+    )
+    goals: Mapped[list["LearnerGoalORM"]] = relationship(back_populates="learner", cascade="all, delete-orphan")
+    enrollments: Mapped[list["EnrollmentORM"]] = relationship(back_populates="learner", cascade="all, delete-orphan")
+    interactions: Mapped[list["InteractionORM"]] = relationship(back_populates="learner", cascade="all, delete-orphan")
+
+
+class LearnerPriorLearningORM(Base):
+    __tablename__ = "learner_prior_learning"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    learner_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("learners.id", ondelete="CASCADE"), nullable=False)
+    learning_type: Mapped[str] = mapped_column(String(20), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    provider: Mapped[str | None] = mapped_column(String(255))
+    description: Mapped[str | None] = mapped_column(Text)
+    evidence_url: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    learner: Mapped["LearnerORM"] = relationship(back_populates="prior_learning_items")
+
+
+class LearnerGoalORM(Base):
+    __tablename__ = "learner_goals"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    learner_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("learners.id", ondelete="CASCADE"), nullable=False)
+    goal_horizon: Mapped[str] = mapped_column(String(20), nullable=False)
+    goal_text: Mapped[str] = mapped_column(Text, nullable=False)
+    target_date: Mapped[datetime | None] = mapped_column(Date)
+    priority: Mapped[int] = mapped_column(Integer, default=3)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+
+    learner: Mapped["LearnerORM"] = relationship(back_populates="goals")
+
+
+class ModuleORM(Base):
+    __tablename__ = "modules"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    code: Mapped[str] = mapped_column(String(50), unique=True, nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    ects_credits: Mapped[float] = mapped_column(Float, default=5.0)
+    difficulty_level: Mapped[str] = mapped_column(String(30), nullable=False)
+    estimated_total_minutes: Mapped[int] = mapped_column(Integer, nullable=False)
+    self_paced: Mapped[bool] = mapped_column(Boolean, default=True)
+    adaptive_enabled: Mapped[bool] = mapped_column(Boolean, default=True)
+    topics: Mapped[list] = mapped_column(JSON, default=list)
+    completion_criteria: Mapped[dict] = mapped_column(JSON, default=dict)
+    prerequisites: Mapped[list] = mapped_column(JSON, default=list)
+    module_vector: Mapped[list] = mapped_column(JSON, default=list)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), onupdate=func.now())
+
+    objectives: Mapped[list["ModuleObjectiveORM"]] = relationship(
+        back_populates="module", cascade="all, delete-orphan", order_by="ModuleObjectiveORM.sort_order"
+    )
+    units: Mapped[list["ModuleUnitORM"]] = relationship(
+        back_populates="module", cascade="all, delete-orphan", order_by="ModuleUnitORM.sort_order"
+    )
+    activities: Mapped[list["ModuleActivityORM"]] = relationship(
+        back_populates="module", cascade="all, delete-orphan", order_by="ModuleActivityORM.sort_order"
+    )
+    assessments: Mapped[list["AssessmentDefinitionORM"]] = relationship(
+        back_populates="module", cascade="all, delete-orphan"
+    )
+
+
+class ModuleObjectiveORM(Base):
+    __tablename__ = "module_objectives"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    module_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("modules.id", ondelete="CASCADE"), nullable=False)
+    text: Mapped[str] = mapped_column(Text, nullable=False)
+    bloom_level: Mapped[str] = mapped_column(String(30), nullable=False)
+    competency_tag: Mapped[str] = mapped_column(String(100), nullable=False)
+    measurable_outcome: Mapped[str] = mapped_column(Text, nullable=False)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+    module: Mapped["ModuleORM"] = relationship(back_populates="objectives")
+
+
+class ModuleUnitORM(Base):
+    __tablename__ = "module_units"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    module_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("modules.id", ondelete="CASCADE"), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    unit_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    chunk_minutes: Mapped[int] = mapped_column(Integer, nullable=False)
+    content_ref: Mapped[str] = mapped_column(Text, nullable=False)
+    adaptive_rules: Mapped[dict] = mapped_column(JSON, default=dict)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+    module: Mapped["ModuleORM"] = relationship(back_populates="units")
+
+
+class ModuleActivityORM(Base):
+    __tablename__ = "module_activities"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    module_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("modules.id", ondelete="CASCADE"), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    activity_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    instructions: Mapped[str] = mapped_column(Text, nullable=False)
+    max_score: Mapped[float | None] = mapped_column(Float)
+    required: Mapped[bool] = mapped_column(Boolean, default=True)
+    sort_order: Mapped[int] = mapped_column(Integer, default=0)
+
+    module: Mapped["ModuleORM"] = relationship(back_populates="activities")
+
+
+class AssessmentDefinitionORM(Base):
+    __tablename__ = "assessments"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    module_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("modules.id", ondelete="CASCADE"), nullable=False)
+    assessment_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    blueprint: Mapped[dict] = mapped_column(JSON, default=dict)
+    time_limit_minutes: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    module: Mapped["ModuleORM"] = relationship(back_populates="assessments")
+    attempts: Mapped[list["AssessmentAttemptORM"]] = relationship(back_populates="assessment")
+
+
+class EnrollmentORM(Base):
+    __tablename__ = "enrollments"
+    __table_args__ = (UniqueConstraint("learner_id", "module_id", name="uq_enrollment_learner_module"),)
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    learner_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("learners.id", ondelete="CASCADE"), nullable=False)
+    module_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("modules.id", ondelete="CASCADE"), nullable=False)
+    enrollment_status: Mapped[str] = mapped_column(String(30), default="active")
+    recommended_by: Mapped[str] = mapped_column(String(30), default="system")
+    started_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    mastery_score: Mapped[float] = mapped_column(Float, default=0.0)
+
+    learner: Mapped["LearnerORM"] = relationship(back_populates="enrollments")
+
+
+class InteractionORM(Base):
+    __tablename__ = "interactions"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    learner_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("learners.id", ondelete="CASCADE"), nullable=False)
+    module_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("modules.id", ondelete="SET NULL"))
+    unit_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True))
+    activity_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True))
+    session_id: Mapped[uuid.UUID | None] = mapped_column(Uuid(as_uuid=True))
+    event_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    event_timestamp: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    duration_ms: Mapped[int | None] = mapped_column(Integer)
+    payload: Mapped[dict] = mapped_column(JSON, default=dict)
+    client_context: Mapped[dict] = mapped_column(JSON, default=dict)
+
+    learner: Mapped["LearnerORM"] = relationship(back_populates="interactions")
+
+
+class AssessmentAttemptORM(Base):
+    __tablename__ = "assessment_attempts"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    assessment_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("assessments.id", ondelete="CASCADE"), nullable=False)
+    learner_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("learners.id", ondelete="CASCADE"), nullable=False)
+    time_limit_minutes: Mapped[int] = mapped_column(Integer, nullable=False)
+    items: Mapped[list] = mapped_column(JSON, default=list)
+    status: Mapped[str] = mapped_column(String(30), default="in_progress")
+    integrity_status: Mapped[str] = mapped_column(String(20), default="pending")
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    score: Mapped[float | None] = mapped_column(Float)
+    pass_status: Mapped[str | None] = mapped_column(String(20))
+    feedback: Mapped[list] = mapped_column(JSON, default=list)
+    human_review_required: Mapped[bool] = mapped_column(Boolean, default=False)
+
+    assessment: Mapped["AssessmentDefinitionORM"] = relationship(back_populates="attempts")

backend/app/models/schemas.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from typing import Any, Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class PriorLearningItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    learning_type: Literal["formal", "non_formal", "informal"]
+    title: str
+    provider: str | None = None
+    description: str | None = None
+
+
+class LearnerGoal(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    goal_horizon: Literal["short_term", "long_term"]
+    goal_text: str
+    target_date: date | None = None
+    priority: int = 3
+
+
+class LearnerPreferences(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    preferred_modalities: list[str] = Field(default_factory=list)
+    preferred_session_length_minutes: int | None = None
+    language_preferences: list[str] = Field(default_factory=list)
+    accessibility_needs: dict[str, Any] = Field(default_factory=dict)
+
+
+class RegisterLearnerRequest(BaseModel):
+    email: EmailStr
+    first_name: str
+    last_name: str
+    locale: str = "en-US"
+    timezone: str
+    educational_level: str
+    consent_personalization: bool = False
+    consent_analytics: bool = False
+    consent_version: str | None = None
+    prior_learning: list[PriorLearningItem]
+    goals: list[LearnerGoal]
+    preferences: LearnerPreferences | None = None
+
+
+class LearnerRegistrationResponse(BaseModel):
+    learner_id: UUID
+    next_step: str = "complete_diagnostic_assessment"
+
+
+class DiagnosticSubmission(BaseModel):
+    responses: list[dict[str, Any]]
+
+
+class UpdateLearnerProfileRequest(BaseModel):
+    goals: list[LearnerGoal] | None = None
+    preferences: LearnerPreferences | None = None
+
+
+class LearnerProfile(BaseModel):
+    learner_id: UUID
+    readiness_level: str
+    readiness_score: float
+    goals: list[LearnerGoal]
+    preferences: LearnerPreferences
+    mastery_map: dict[str, float]
+    risk_profile: dict[str, Any]
+    profile_vector: list[float]
+
+
+class ModuleObjective(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    text: str
+    bloom_level: str
+    competency_tag: str
+    measurable_outcome: str
+
+
+class ModuleUnit(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    title: str
+    unit_type: str
+    chunk_minutes: int
+    content_ref: str
+    adaptive_rules: dict[str, Any] = Field(default_factory=dict)
+
+
+class ModuleActivity(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    title: str
+    activity_type: str
+    instructions: str
+    max_score: float | None = None
+    required: bool = True
+
+
+class ModuleCompletionCriteria(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    min_unit_completion_ratio: float
+    min_formative_score: float
+    require_summative_pass: bool = True
+    min_time_on_task_minutes: int | None = None
+    integrity_clearance_required: bool = True
+
+
+class ModuleSummary(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    code: str
+    title: str
+    description: str
+    ects_credits: float = 5.0
+    difficulty_level: str
+    estimated_total_minutes: int
+    self_paced: bool = True
+    adaptive_enabled: bool = True
+    topics: list[str] = Field(default_factory=list)
+
+
+class ModuleDetail(ModuleSummary):
+    objectives: list[ModuleObjective]
+    units: list[ModuleUnit]
+    activities: list[ModuleActivity]
+    completion_criteria: ModuleCompletionCriteria
+    prerequisites: list[UUID] = Field(default_factory=list)
+    module_vector: list[float] = Field(default_factory=list)
+
+
+class RecommendationItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    module_id: UUID
+    rank: int
+    score: float
+    reasons: list[str]
+
+
+class RecommendationResponse(BaseModel):
+    learner_id: UUID
+    generated_at: datetime = Field(default_factory=utcnow)
+    items: list[RecommendationItem]
+
+
+class EnrollmentCreate(BaseModel):
+    learner_id: UUID
+    module_id: UUID
+
+
+class Enrollment(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    learner_id: UUID
+    module_id: UUID
+    enrollment_status: str = "active"
+    recommended_by: str = "system"
+    started_at: datetime | None = Field(default_factory=utcnow)
+    completed_at: datetime | None = None
+    mastery_score: float = 0.0
+
+
+class ProgressItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    module_id: UUID
+    completion_percent: float
+    mastery_score: float
+    next_recommended_action: str
+
+
+class ProgressSummary(BaseModel):
+    learner_id: UUID
+    active_enrollments: list[ProgressItem]
+
+
+class InteractionEvent(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    learner_id: UUID
+    module_id: UUID | None = None
+    unit_id: UUID | None = None
+    activity_id: UUID | None = None
+    session_id: UUID | None = None
+    event_type: str
+    event_timestamp: datetime = Field(default_factory=utcnow)
+    duration_ms: int | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+    client_context: dict[str, Any] = Field(default_factory=dict)
+
+
+class AssessmentAttemptCreate(BaseModel):
+    learner_id: UUID
+
+
+class AssessmentItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    question_id: UUID = Field(default_factory=uuid4)
+    question_type: str
+    prompt: str
+    objective_tag: str
+    time_limit_seconds: int | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class AssessmentAttempt(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    attempt_id: UUID = Field(default_factory=uuid4)
+    assessment_id: UUID
+    learner_id: UUID
+    time_limit_minutes: int
+    items: list[AssessmentItem]
+    status: str = "in_progress"
+    integrity_status: str = "pending"
+    created_at: datetime = Field(default_factory=utcnow)
+
+
+class AssessmentResponseItem(BaseModel):
+    question_id: UUID
+    answer: Any
+
+
+class AssessmentResponseSubmission(BaseModel):
+    responses: list[AssessmentResponseItem]
+
+
+class AssessmentAttemptResult(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    attempt_id: UUID
+    score: float
+    pass_status: str
+    integrity_status: str
+    feedback: list[str]
+    human_review_required: bool = False
+
+
+class LearnerDashboard(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    learner_id: UUID
+    mastery: dict[str, float]
+    time_on_task_minutes_7d: float
+    dropout_risk: float
+    success_probability: float
+    adaptive_feedback: list[str]
+
+
+class LearnerRecord(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    email: EmailStr
+    first_name: str
+    last_name: str
+    locale: str
+    timezone: str
+    educational_level: str
+    consent_personalization: bool
+    consent_analytics: bool
+    consent_version: str | None = None
+    prior_learning: list[PriorLearningItem] = Field(default_factory=list)
+    goals: list[LearnerGoal] = Field(default_factory=list)
+    preferences: LearnerPreferences = Field(default_factory=LearnerPreferences)
+    readiness_level: str = "unknown"
+    readiness_score: float = 0.0
+    mastery_map: dict[str, float] = Field(default_factory=dict)
+    risk_profile: dict[str, Any] = Field(default_factory=dict)
+    profile_vector: list[float] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=utcnow)
+
+
+class AssessmentDefinition(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    module_id: UUID
+    assessment_type: str
+    title: str
+    blueprint: dict[str, Any]
+    time_limit_minutes: int
+
+
+class StoredInteraction(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    event: InteractionEvent

backend/app/services/__init__.py

@@ -0,0 +1 @@
+"""Domain services for recommendations, assessments, analytics, and storage."""

backend/app/services/bootstrap.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.schemas import (
+    AssessmentDefinition,
+    ModuleActivity,
+    ModuleCompletionCriteria,
+    ModuleDetail,
+    ModuleObjective,
+    ModuleUnit,
+)
+from app.services import repository
+
+
+async def seed_demo_data(session: AsyncSession) -> None:
+    if await repository.has_modules(session):
+        return
+
+    module_one = ModuleDetail(
+        id="11111111-1111-1111-1111-111111111111",
+        code="AID-101",
+        title="AI-Supported Self-Regulated Learning",
+        description="Introduces learners to using AI for planning, monitoring, and reflecting on self-directed study.",
+        difficulty_level="foundation",
+        estimated_total_minutes=750,
+        topics=["self-regulation", "ai literacy"],
+        objectives=[
+            ModuleObjective(
+                text="Explain how AI tools can support planning and self-monitoring.",
+                bloom_level="understand",
+                competency_tag="self_regulated_learning",
+                measurable_outcome="Learner explains planning and monitoring strategies.",
+            ),
+            ModuleObjective(
+                text="Apply AI-supported reflection to improve study habits.",
+                bloom_level="apply",
+                competency_tag="reflective_practice",
+                measurable_outcome="Learner produces an evidence-based reflection.",
+            ),
+        ],
+        units=[
+            ModuleUnit(
+                title="Planning with AI",
+                unit_type="video",
+                chunk_minutes=12,
+                content_ref="/content/modules/aid-101/planning-with-ai",
+            ),
+            ModuleUnit(
+                title="Monitoring Progress",
+                unit_type="reading",
+                chunk_minutes=10,
+                content_ref="/content/modules/aid-101/monitoring-progress",
+            ),
+        ],
+        activities=[
+            ModuleActivity(
+                title="Study Strategy Reflection",
+                activity_type="reflection",
+                instructions="Reflect on how AI could improve your weekly study routine.",
+                max_score=20,
+            )
+        ],
+        completion_criteria=ModuleCompletionCriteria(
+            min_unit_completion_ratio=0.85,
+            min_formative_score=70,
+            min_time_on_task_minutes=300,
+        ),
+        module_vector=[0.35, 0.7, 0.5],
+    )
+
+    module_two = ModuleDetail(
+        id="22222222-2222-2222-2222-222222222222",
+        code="AID-205",
+        title="Scenario-Based Problem Solving with AI",
+        description="Builds authentic problem-solving skills through case analysis and AI-supported reasoning.",
+        difficulty_level="intermediate",
+        estimated_total_minutes=780,
+        topics=["problem solving", "scenario analysis"],
+        objectives=[
+            ModuleObjective(
+                text="Analyze scenario constraints and choose suitable AI-supported strategies.",
+                bloom_level="analyze",
+                competency_tag="applied_ai_literacy",
+                measurable_outcome="Learner compares alternative strategies in a case.",
+            ),
+            ModuleObjective(
+                text="Evaluate outputs for reliability, bias, and usefulness.",
+                bloom_level="evaluate",
+                competency_tag="critical_evaluation",
+                measurable_outcome="Learner critiques AI output quality.",
+            ),
+        ],
+        units=[
+            ModuleUnit(
+                title="Interpreting Realistic Cases",
+                unit_type="simulation",
+                chunk_minutes=15,
+                content_ref="/content/modules/aid-205/interpreting-cases",
+            ),
+            ModuleUnit(
+                title="Evaluating AI Output",
+                unit_type="interactive",
+                chunk_minutes=14,
+                content_ref="/content/modules/aid-205/evaluating-output",
+            ),
+        ],
+        activities=[
+            ModuleActivity(
+                title="Case Analysis Quiz",
+                activity_type="quiz",
+                instructions="Select and justify the best response in each scenario.",
+                max_score=30,
+            )
+        ],
+        completion_criteria=ModuleCompletionCriteria(
+            min_unit_completion_ratio=0.9,
+            min_formative_score=75,
+            min_time_on_task_minutes=320,
+        ),
+        prerequisites=["11111111-1111-1111-1111-111111111111"],
+        module_vector=[0.65, 0.8, 0.6],
+    )
+
+    await repository.create_module(session, module_one)
+    await repository.create_module(session, module_two)
+
+    await repository.create_assessment(
+        session,
+        AssessmentDefinition(
+            id="33333333-3333-3333-3333-333333333333",
+            module_id=module_one.id,
+            assessment_type="summative",
+            title="AID-101 Summative Assessment",
+            blueprint={
+                "objectives": ["self_regulated_learning", "reflective_practice"],
+                "time_per_item_seconds": 420,
+            },
+            time_limit_minutes=45,
+        )
+    )

backend/app/services/engines.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from statistics import mean
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.schemas import (
+    AssessmentAttempt,
+    AssessmentAttemptResult,
+    AssessmentDefinition,
+    AssessmentItem,
+    DiagnosticSubmission,
+    InteractionEvent,
+    LearnerDashboard,
+    LearnerProfile,
+    LearnerRecord,
+    ModuleDetail,
+    ProgressItem,
+    ProgressSummary,
+    RecommendationItem,
+    RecommendationResponse,
+)
+from app.services import repository
+
+
+def build_profile(learner: LearnerRecord, diagnostic: DiagnosticSubmission | None = None) -> LearnerRecord:
+    prior_score = min(len(learner.prior_learning) / 10, 1.0)
+    goal_score = min(len(learner.goals) / 5, 1.0)
+    pref_score = 0.2 if learner.preferences.preferred_modalities else 0.0
+    readiness = 0.5
+
+    if diagnostic and diagnostic.responses:
+        raw = mean(float(item.get("score", 0.5)) for item in diagnostic.responses)
+        readiness = max(0.0, min(raw, 1.0))
+
+    learner.readiness_score = round(readiness * 100, 2)
+    learner.readiness_level = (
+        "advanced" if readiness >= 0.75 else "intermediate" if readiness >= 0.45 else "foundation"
+    )
+    learner.profile_vector = [
+        round(prior_score, 4),
+        round(goal_score, 4),
+        round(pref_score, 4),
+        round(readiness, 4),
+    ]
+    learner.mastery_map = {
+        "self_regulated_learning": round(readiness, 2),
+        "applied_ai_literacy": round((prior_score + readiness) / 2, 2),
+        "reflective_practice": round((goal_score + pref_score + readiness) / 2, 2),
+    }
+    learner.risk_profile = {
+        "dropout_risk": round(max(0.1, 1 - readiness), 2),
+        "recommended_support_level": "high" if readiness < 0.4 else "standard",
+    }
+    return learner
+
+
+def learner_to_profile(learner: LearnerRecord) -> LearnerProfile:
+    return LearnerProfile(
+        learner_id=learner.id,
+        readiness_level=learner.readiness_level,
+        readiness_score=learner.readiness_score,
+        goals=learner.goals,
+        preferences=learner.preferences,
+        mastery_map=learner.mastery_map,
+        risk_profile=learner.risk_profile,
+        profile_vector=learner.profile_vector,
+    )
+
+
+def rank_modules(learner: LearnerRecord, modules: list[ModuleDetail]) -> RecommendationResponse:
+    scored: list[RecommendationItem] = []
+    learner_topics = {goal.goal_text.lower() for goal in learner.goals}
+
+    for module in modules:
+        topic_match = sum(1 for topic in module.topics if any(topic.lower() in g for g in learner_topics))
+        readiness_alignment = 1 - abs((learner.readiness_score / 100) - module.module_vector[0])
+        workload_score = 1 - min(module.estimated_total_minutes / 1500, 1.0)
+        score = round(0.45 * topic_match + 0.35 * readiness_alignment + 0.20 * workload_score, 4)
+        reasons = [
+            f"Aligned with {module.topics[0] if module.topics else 'your stated goals'}",
+            f"Suitable for {learner.readiness_level} readiness",
+            "Supports a self-paced 5 ECTS pathway",
+        ]
+        scored.append(RecommendationItem(module_id=module.id, rank=0, score=score, reasons=reasons))
+
+    ranked = sorted(scored, key=lambda item: item.score, reverse=True)
+    for index, item in enumerate(ranked, start=1):
+        item.rank = index
+
+    return RecommendationResponse(learner_id=learner.id, items=ranked[:10])
+
+
+def generate_assessment_attempt(assessment: AssessmentDefinition, learner_id: UUID) -> AssessmentAttempt:
+    objectives = assessment.blueprint.get("objectives", [])
+    items = [
+        AssessmentItem(
+            question_type="scenario_open",
+            prompt=f"Scenario {index + 1}: Apply {objective} in a realistic learning context and justify your response.",
+            objective_tag=objective,
+            time_limit_seconds=assessment.blueprint.get("time_per_item_seconds", 300),
+            metadata={"unique_variant_seed": f"{learner_id}-{index}"},
+        )
+        for index, objective in enumerate(objectives)
+    ]
+    return AssessmentAttempt(
+        assessment_id=assessment.id,
+        learner_id=learner_id,
+        time_limit_minutes=assessment.time_limit_minutes,
+        items=items,
+    )
+
+
+def evaluate_attempt(attempt: AssessmentAttempt, responses_count: int) -> AssessmentAttemptResult:
+    completion_ratio = responses_count / max(len(attempt.items), 1)
+    score = round(min(100.0, 55 + completion_ratio * 45), 2)
+    integrity_status = "review" if responses_count < len(attempt.items) else "pass"
+    pass_status = "pass" if score >= 70 and integrity_status == "pass" else "review"
+    feedback = [
+        "Responses were evaluated against module objectives and participation thresholds.",
+        "Final certification should also check plagiarism and anomaly signals in production.",
+    ]
+    return AssessmentAttemptResult(
+        attempt_id=attempt.attempt_id,
+        score=score,
+        pass_status=pass_status,
+        integrity_status=integrity_status,
+        feedback=feedback,
+        human_review_required=integrity_status != "pass",
+    )
+
+
+async def build_progress_summary(session: AsyncSession, learner_id: UUID) -> ProgressSummary:
+    enrollments = await repository.list_enrollments_for_learner(session, learner_id)
+    interactions = await repository.list_interactions_for_learner(session, learner_id)
+    summary_items: list[ProgressItem] = []
+
+    for enrollment in enrollments:
+        module_events = [i for i in interactions if i.module_id == enrollment.module_id]
+        completion = min(len(module_events) * 10.0, 100.0)
+        mastery = round(min(100.0, 40 + len(module_events) * 5.5), 2)
+        summary_items.append(
+            ProgressItem(
+                module_id=enrollment.module_id,
+                completion_percent=completion,
+                mastery_score=mastery,
+                next_recommended_action="Complete the next content chunk and formative reflection.",
+            )
+        )
+
+    return ProgressSummary(learner_id=learner_id, active_enrollments=summary_items)
+
+
+async def build_dashboard(session: AsyncSession, learner: LearnerRecord) -> LearnerDashboard:
+    interactions = await repository.list_interactions_for_learner(session, learner.id)
+    total_minutes = round(sum((item.duration_ms or 0) for item in interactions) / 60000, 2)
+    dropout_risk = learner.risk_profile.get("dropout_risk", 0.3)
+    success_probability = round(max(0.2, 1 - dropout_risk + 0.15), 2)
+
+    return LearnerDashboard(
+        learner_id=learner.id,
+        mastery=learner.mastery_map,
+        time_on_task_minutes_7d=total_minutes,
+        dropout_risk=dropout_risk,
+        success_probability=success_probability,
+        adaptive_feedback=[
+            "Continue with short focused sessions of 10 to 15 minutes.",
+            "Prioritize scenario-based practice to improve transfer and assessment performance.",
+        ],
+    )

backend/app/services/repository.py

@@ -0,0 +1,471 @@
+from __future__ import annotations
+
+from uuid import UUID
+
+from fastapi import HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from app.models.orm import (
+    AssessmentAttemptORM,
+    AssessmentDefinitionORM,
+    EnrollmentORM,
+    InteractionORM,
+    LearnerGoalORM,
+    LearnerORM,
+    LearnerPriorLearningORM,
+    ModuleActivityORM,
+    ModuleORM,
+    ModuleObjectiveORM,
+    ModuleUnitORM,
+)
+from app.models.schemas import (
+    AssessmentAttempt,
+    AssessmentAttemptResult,
+    AssessmentDefinition,
+    Enrollment,
+    InteractionEvent,
+    LearnerGoal,
+    LearnerPreferences,
+    LearnerProfile,
+    LearnerRecord,
+    ModuleActivity,
+    ModuleCompletionCriteria,
+    ModuleDetail,
+    ModuleObjective,
+    ModuleUnit,
+    PriorLearningItem,
+)
+
+
+def _learner_to_schema(model: LearnerORM) -> LearnerRecord:
+    return LearnerRecord(
+        id=model.id,
+        email=model.email,
+        first_name=model.first_name,
+        last_name=model.last_name,
+        locale=model.locale,
+        timezone=model.timezone,
+        educational_level=model.educational_level,
+        consent_personalization=model.consent_personalization,
+        consent_analytics=model.consent_analytics,
+        consent_version=model.consent_version,
+        prior_learning=[
+            PriorLearningItem(
+                learning_type=item.learning_type,
+                title=item.title,
+                provider=item.provider,
+                description=item.description,
+            )
+            for item in model.prior_learning_items
+        ],
+        goals=[
+            LearnerGoal(
+                goal_horizon=item.goal_horizon,
+                goal_text=item.goal_text,
+                target_date=item.target_date,
+                priority=item.priority,
+            )
+            for item in model.goals
+        ],
+        preferences=LearnerPreferences.model_validate(model.preferences or {}),
+        readiness_level=model.readiness_level,
+        readiness_score=model.readiness_score,
+        mastery_map=model.mastery_map or {},
+        risk_profile=model.risk_profile or {},
+        profile_vector=model.profile_vector or [],
+        created_at=model.created_at,
+    )
+
+
+def _module_to_schema(model: ModuleORM) -> ModuleDetail:
+    return ModuleDetail(
+        id=model.id,
+        code=model.code,
+        title=model.title,
+        description=model.description,
+        ects_credits=model.ects_credits,
+        difficulty_level=model.difficulty_level,
+        estimated_total_minutes=model.estimated_total_minutes,
+        self_paced=model.self_paced,
+        adaptive_enabled=model.adaptive_enabled,
+        topics=model.topics or [],
+        objectives=[
+            ModuleObjective(
+                id=item.id,
+                text=item.text,
+                bloom_level=item.bloom_level,
+                competency_tag=item.competency_tag,
+                measurable_outcome=item.measurable_outcome,
+            )
+            for item in model.objectives
+        ],
+        units=[
+            ModuleUnit(
+                id=item.id,
+                title=item.title,
+                unit_type=item.unit_type,
+                chunk_minutes=item.chunk_minutes,
+                content_ref=item.content_ref,
+                adaptive_rules=item.adaptive_rules or {},
+            )
+            for item in model.units
+        ],
+        activities=[
+            ModuleActivity(
+                id=item.id,
+                title=item.title,
+                activity_type=item.activity_type,
+                instructions=item.instructions,
+                max_score=item.max_score,
+                required=item.required,
+            )
+            for item in model.activities
+        ],
+        completion_criteria=ModuleCompletionCriteria.model_validate(model.completion_criteria or {}),
+        prerequisites=model.prerequisites or [],
+        module_vector=model.module_vector or [],
+    )
+
+
+def _assessment_to_schema(model: AssessmentDefinitionORM) -> AssessmentDefinition:
+    return AssessmentDefinition(
+        id=model.id,
+        module_id=model.module_id,
+        assessment_type=model.assessment_type,
+        title=model.title,
+        blueprint=model.blueprint or {},
+        time_limit_minutes=model.time_limit_minutes,
+    )
+
+
+def _attempt_to_schema(model: AssessmentAttemptORM) -> AssessmentAttempt:
+    return AssessmentAttempt(
+        attempt_id=model.id,
+        assessment_id=model.assessment_id,
+        learner_id=model.learner_id,
+        time_limit_minutes=model.time_limit_minutes,
+        items=model.items or [],
+        status=model.status,
+        integrity_status=model.integrity_status,
+        created_at=model.created_at,
+    )
+
+
+async def create_learner(session: AsyncSession, record: LearnerRecord) -> LearnerRecord:
+    learner = LearnerORM(
+        id=record.id,
+        email=str(record.email),
+        first_name=record.first_name,
+        last_name=record.last_name,
+        locale=record.locale,
+        timezone=record.timezone,
+        educational_level=record.educational_level,
+        consent_personalization=record.consent_personalization,
+        consent_analytics=record.consent_analytics,
+        consent_version=record.consent_version,
+        readiness_level=record.readiness_level,
+        readiness_score=record.readiness_score,
+        mastery_map=record.mastery_map,
+        risk_profile=record.risk_profile,
+        profile_vector=record.profile_vector,
+        preferences=record.preferences.model_dump(),
+        prior_learning_items=[
+            LearnerPriorLearningORM(
+                learning_type=item.learning_type,
+                title=item.title,
+                provider=item.provider,
+                description=item.description,
+            )
+            for item in record.prior_learning
+        ],
+        goals=[
+            LearnerGoalORM(
+                goal_horizon=item.goal_horizon,
+                goal_text=item.goal_text,
+                target_date=item.target_date,
+                priority=item.priority,
+            )
+            for item in record.goals
+        ],
+    )
+    session.add(learner)
+    await session.commit()
+    await session.refresh(learner)
+    return await get_learner(session, learner.id)
+
+
+async def update_learner(session: AsyncSession, record: LearnerRecord) -> LearnerRecord:
+    learner = await session.get(LearnerORM, record.id, options=(selectinload(LearnerORM.prior_learning_items), selectinload(LearnerORM.goals)))
+    if learner is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Learner not found")
+
+    learner.first_name = record.first_name
+    learner.last_name = record.last_name
+    learner.locale = record.locale
+    learner.timezone = record.timezone
+    learner.educational_level = record.educational_level
+    learner.consent_personalization = record.consent_personalization
+    learner.consent_analytics = record.consent_analytics
+    learner.consent_version = record.consent_version
+    learner.readiness_level = record.readiness_level
+    learner.readiness_score = record.readiness_score
+    learner.mastery_map = record.mastery_map
+    learner.risk_profile = record.risk_profile
+    learner.profile_vector = record.profile_vector
+    learner.preferences = record.preferences.model_dump()
+    learner.prior_learning_items = [
+        LearnerPriorLearningORM(
+            learning_type=item.learning_type,
+            title=item.title,
+            provider=item.provider,
+            description=item.description,
+        )
+        for item in record.prior_learning
+    ]
+    learner.goals = [
+        LearnerGoalORM(
+            goal_horizon=item.goal_horizon,
+            goal_text=item.goal_text,
+            target_date=item.target_date,
+            priority=item.priority,
+        )
+        for item in record.goals
+    ]
+    await session.commit()
+    return await get_learner(session, learner.id)
+
+
+async def get_learner(session: AsyncSession, learner_id: UUID) -> LearnerRecord:
+    stmt = (
+        select(LearnerORM)
+        .where(LearnerORM.id == learner_id)
+        .options(selectinload(LearnerORM.prior_learning_items), selectinload(LearnerORM.goals))
+    )
+    learner = (await session.execute(stmt)).scalar_one_or_none()
+    if learner is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Learner not found")
+    return _learner_to_schema(learner)
+
+
+async def list_modules(session: AsyncSession) -> list[ModuleDetail]:
+    stmt = select(ModuleORM).options(
+        selectinload(ModuleORM.objectives),
+        selectinload(ModuleORM.units),
+        selectinload(ModuleORM.activities),
+    )
+    modules = (await session.execute(stmt)).scalars().all()
+    return [_module_to_schema(item) for item in modules]
+
+
+async def get_module(session: AsyncSession, module_id: UUID) -> ModuleDetail:
+    stmt = (
+        select(ModuleORM)
+        .where(ModuleORM.id == module_id)
+        .options(selectinload(ModuleORM.objectives), selectinload(ModuleORM.units), selectinload(ModuleORM.activities))
+    )
+    module = (await session.execute(stmt)).scalar_one_or_none()
+    if module is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Module not found")
+    return _module_to_schema(module)
+
+
+async def create_module(session: AsyncSession, module: ModuleDetail) -> ModuleDetail:
+    module_orm = ModuleORM(
+        id=module.id,
+        code=module.code,
+        title=module.title,
+        description=module.description,
+        ects_credits=module.ects_credits,
+        difficulty_level=module.difficulty_level,
+        estimated_total_minutes=module.estimated_total_minutes,
+        self_paced=module.self_paced,
+        adaptive_enabled=module.adaptive_enabled,
+        topics=module.topics,
+        completion_criteria=module.completion_criteria.model_dump(),
+        prerequisites=[str(item) for item in module.prerequisites],
+        module_vector=module.module_vector,
+        objectives=[
+            ModuleObjectiveORM(
+                id=item.id,
+                text=item.text,
+                bloom_level=item.bloom_level,
+                competency_tag=item.competency_tag,
+                measurable_outcome=item.measurable_outcome,
+                sort_order=index,
+            )
+            for index, item in enumerate(module.objectives)
+        ],
+        units=[
+            ModuleUnitORM(
+                id=item.id,
+                title=item.title,
+                unit_type=item.unit_type,
+                chunk_minutes=item.chunk_minutes,
+                content_ref=item.content_ref,
+                adaptive_rules=item.adaptive_rules,
+                sort_order=index,
+            )
+            for index, item in enumerate(module.units)
+        ],
+        activities=[
+            ModuleActivityORM(
+                id=item.id,
+                title=item.title,
+                activity_type=item.activity_type,
+                instructions=item.instructions,
+                max_score=item.max_score,
+                required=item.required,
+                sort_order=index,
+            )
+            for index, item in enumerate(module.activities)
+        ],
+    )
+    session.add(module_orm)
+    await session.commit()
+    return await get_module(session, module.id)
+
+
+async def create_assessment(session: AsyncSession, definition: AssessmentDefinition) -> AssessmentDefinition:
+    assessment = AssessmentDefinitionORM(
+        id=definition.id,
+        module_id=definition.module_id,
+        assessment_type=definition.assessment_type,
+        title=definition.title,
+        blueprint=definition.blueprint,
+        time_limit_minutes=definition.time_limit_minutes,
+    )
+    session.add(assessment)
+    await session.commit()
+    return await get_assessment(session, definition.id)
+
+
+async def get_assessment(session: AsyncSession, assessment_id: UUID) -> AssessmentDefinition:
+    assessment = await session.get(AssessmentDefinitionORM, assessment_id)
+    if assessment is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Assessment not found")
+    return _assessment_to_schema(assessment)
+
+
+async def create_enrollment(session: AsyncSession, enrollment: Enrollment) -> Enrollment:
+    model = EnrollmentORM(
+        id=enrollment.id,
+        learner_id=enrollment.learner_id,
+        module_id=enrollment.module_id,
+        enrollment_status=enrollment.enrollment_status,
+        recommended_by=enrollment.recommended_by,
+        mastery_score=enrollment.mastery_score,
+        completed_at=enrollment.completed_at,
+    )
+    session.add(model)
+    await session.commit()
+    await session.refresh(model)
+    return Enrollment.model_validate(model)
+
+
+async def list_enrollments_for_learner(session: AsyncSession, learner_id: UUID) -> list[Enrollment]:
+    stmt = select(EnrollmentORM).where(EnrollmentORM.learner_id == learner_id)
+    enrollments = (await session.execute(stmt)).scalars().all()
+    return [Enrollment.model_validate(item) for item in enrollments]
+
+
+async def create_interaction(session: AsyncSession, event: InteractionEvent) -> InteractionEvent:
+    model = InteractionORM(
+        learner_id=event.learner_id,
+        module_id=event.module_id,
+        unit_id=event.unit_id,
+        activity_id=event.activity_id,
+        session_id=event.session_id,
+        event_type=event.event_type,
+        event_timestamp=event.event_timestamp,
+        duration_ms=event.duration_ms,
+        payload=event.payload,
+        client_context=event.client_context,
+    )
+    session.add(model)
+    await session.commit()
+    return event
+
+
+async def list_interactions_for_learner(session: AsyncSession, learner_id: UUID) -> list[InteractionEvent]:
+    stmt = select(InteractionORM).where(InteractionORM.learner_id == learner_id)
+    interactions = (await session.execute(stmt)).scalars().all()
+    return [
+        InteractionEvent(
+            learner_id=item.learner_id,
+            module_id=item.module_id,
+            unit_id=item.unit_id,
+            activity_id=item.activity_id,
+            session_id=item.session_id,
+            event_type=item.event_type,
+            event_timestamp=item.event_timestamp,
+            duration_ms=item.duration_ms,
+            payload=item.payload or {},
+            client_context=item.client_context or {},
+        )
+        for item in interactions
+    ]
+
+
+async def create_attempt(session: AsyncSession, attempt: AssessmentAttempt) -> AssessmentAttempt:
+    model = AssessmentAttemptORM(
+        id=attempt.attempt_id,
+        assessment_id=attempt.assessment_id,
+        learner_id=attempt.learner_id,
+        time_limit_minutes=attempt.time_limit_minutes,
+        items=[item.model_dump(mode="json") for item in attempt.items],
+        status=attempt.status,
+        integrity_status=attempt.integrity_status,
+    )
+    session.add(model)
+    await session.commit()
+    return await get_attempt(session, attempt.attempt_id)
+
+
+async def get_attempt(session: AsyncSession, attempt_id: UUID) -> AssessmentAttempt:
+    attempt = await session.get(AssessmentAttemptORM, attempt_id)
+    if attempt is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Assessment attempt not found")
+    return _attempt_to_schema(attempt)
+
+
+async def save_result(session: AsyncSession, result: AssessmentAttemptResult) -> AssessmentAttemptResult:
+    attempt = await session.get(AssessmentAttemptORM, result.attempt_id)
+    if attempt is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Assessment attempt not found")
+    attempt.score = result.score
+    attempt.pass_status = result.pass_status
+    attempt.integrity_status = result.integrity_status
+    attempt.feedback = result.feedback
+    attempt.human_review_required = result.human_review_required
+    attempt.status = "completed"
+    await session.commit()
+    return result
+
+
+async def get_result(session: AsyncSession, attempt_id: UUID) -> AssessmentAttemptResult:
+    attempt = await session.get(AssessmentAttemptORM, attempt_id)
+    if attempt is None or attempt.score is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Assessment result not ready")
+    return AssessmentAttemptResult(
+        attempt_id=attempt.id,
+        score=attempt.score,
+        pass_status=attempt.pass_status or "review",
+        integrity_status=attempt.integrity_status,
+        feedback=attempt.feedback or [],
+        human_review_required=attempt.human_review_required,
+    )
+
+
+async def module_exists(session: AsyncSession, module_id: UUID) -> bool:
+    return await session.get(ModuleORM, module_id) is not None
+
+
+async def learner_exists(session: AsyncSession, learner_id: UUID) -> bool:
+    return await session.get(LearnerORM, learner_id) is not None
+
+
+async def has_modules(session: AsyncSession) -> bool:
+    stmt = select(ModuleORM.id).limit(1)
+    return (await session.execute(stmt)).first() is not None

backend/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "aididact-backend"
+version = "0.1.0"
+description = "FastAPI scaffold for the AIDidact AI-powered microlearning ecosystem."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "fastapi==0.116.1",
+  "uvicorn[standard]==0.35.0",
+  "pydantic==2.11.7",
+  "pydantic-settings==2.10.1",
+  "email-validator==2.2.0",
+  "sqlalchemy==2.0.43",
+  "asyncpg==0.30.0",
+  "alembic==1.16.4",
+  "greenlet==3.2.4",
+  "aiosqlite==0.21.0",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

backend/requirements.txt

@@ -0,0 +1,10 @@
+fastapi==0.116.1
+uvicorn[standard]==0.35.0
+pydantic==2.11.7
+pydantic-settings==2.10.1
+email-validator==2.2.0
+sqlalchemy==2.0.43
+asyncpg==0.30.0
+alembic==1.16.4
+greenlet==3.2.4
+aiosqlite==0.21.0

docs/algorithms.md

@@ -0,0 +1,149 @@
+# Core Algorithms
+
+## 1. Learner Profile Vector
+
+```text
+FUNCTION build_learner_profile_vector(registration, diagnostic, history):
+  prior_learning_embedding = embed(registration.prior_learning)
+  goal_embedding = embed(registration.goals)
+  education_features = encode_categorical(registration.educational_level)
+  readiness_features = normalize(diagnostic.scores)
+  preference_features = encode_optional(registration.preferences)
+  behavior_features = aggregate(history)
+
+  profile_vector = concatenate(
+    prior_learning_embedding,
+    goal_embedding,
+    education_features,
+    readiness_features,
+    preference_features,
+    behavior_features
+  )
+
+  mastery_map = initialize_mastery(diagnostic)
+  RETURN { profile_vector, mastery_map }
+```
+
+## 2. Module Vectorization
+
+```text
+FUNCTION build_module_vector(module):
+  objective_embedding = embed(module.objectives)
+  topic_embedding = embed(module.topics)
+  bloom_features = encode_bloom_levels(module.objectives)
+  workload_features = normalize(module.estimated_minutes, module.ects)
+  activity_features = encode_multilabel(module.activity_types)
+  prerequisite_features = encode_graph_position(module.prerequisites)
+
+  RETURN concatenate(
+    objective_embedding,
+    topic_embedding,
+    bloom_features,
+    workload_features,
+    activity_features,
+    prerequisite_features
+  )
+```
+
+## 3. Hybrid Recommendation
+
+```text
+FUNCTION recommend_modules(learner, candidates):
+  FOR module IN candidates:
+    content_score = cosine_similarity(learner.profile_vector, module.vector)
+    collaborative_score = collaborative_model.predict(learner.id, module.id)
+    readiness_score = readiness_alignment(learner.mastery_map, module.required_competencies)
+    pacing_score = pace_alignment(learner, module)
+    diversity_penalty = novelty_penalty(learner.recent_topics, module.topic_cluster)
+
+    final_score =
+      0.35 * content_score +
+      0.30 * collaborative_score +
+      0.20 * readiness_score +
+      0.15 * pacing_score -
+      diversity_penalty
+
+    IF not prerequisites_satisfied(learner, module):
+      final_score = -INF
+
+  RETURN top_k_by_score(candidates)
+```
+
+## 4. Dynamic Assessment Generation
+
+```text
+FUNCTION generate_unique_assessment(blueprint, learner):
+  selected_items = []
+
+  FOR objective IN blueprint.objectives:
+    pool = filter_question_pool(
+      objective=objective,
+      difficulty=target_difficulty(learner, objective)
+    )
+
+    item = choose_unique_variant(pool, learner.previous_items)
+
+    IF item.parameterized:
+      item = inject_unique_parameters(item, learner.id, now())
+
+    IF item.ai_generatable:
+      item = ai_generate_variant(item.template, blueprint.rubric)
+
+    selected_items.append(item)
+
+  RETURN shuffle(selected_items)
+```
+
+## 5. Open-Ended AI Evaluation
+
+```text
+FUNCTION evaluate_open_response(response, rubric):
+  deterministic_checks = run_basic_checks(response, rubric)
+  ai_result = ai_score_with_rubric(response.text, rubric)
+  final_score = weighted_merge(deterministic_checks, ai_result.score)
+
+  save_audit_trace(response.id, rubric, ai_result.rationale, ai_result.confidence)
+
+  IF ai_result.confidence < 0.60:
+    queue_human_review(response.id)
+
+  RETURN final_score
+```
+
+## 6. Integrity Detection
+
+```text
+FUNCTION integrity_check(attempt):
+  plagiarism = compare_to_corpus(attempt.responses)
+  peer_similarity = compare_to_peer_attempts(attempt)
+  timing_anomaly = detect_impossible_timing(attempt.event_stream)
+  session_anomaly = detect_session_irregularity(attempt.session_metadata)
+
+  risk = weighted_sum(plagiarism, peer_similarity, timing_anomaly, session_anomaly)
+
+  IF risk >= 0.85:
+    RETURN "block"
+  IF risk >= 0.60:
+    RETURN "review"
+  RETURN "pass"
+```
+
+## 7. Dropout Risk Prediction
+
+```text
+FUNCTION predict_dropout_risk(learner_features):
+  risk_probability = dropout_model.predict([
+    learner_features.time_on_task_7d,
+    learner_features.inactivity_days,
+    learner_features.quiz_failure_rate,
+    learner_features.pace_slippage,
+    learner_features.unfinished_activity_ratio
+  ])
+
+  IF risk_probability > 0.75:
+    trigger_high_priority_intervention()
+  ELSE IF risk_probability > 0.45:
+    trigger_nudge()
+
+  RETURN risk_probability
+```

docs/architecture.md

@@ -0,0 +1,114 @@
+# AIDidact Architecture Blueprint
+
+## 1. Core Components
+
+### Learner profiling system
+
+- Collects formal, non-formal, and informal prior learning.
+- Captures short-term and long-term learning goals.
+- Stores educational level and diagnostic readiness.
+- Accepts optional learning preferences such as modality and pacing.
+- Produces a learner profile vector and baseline mastery map.
+
+### Microlearning module system
+
+Each 5 ECTS module contains:
+
+- Bloom-aligned learning objectives
+- content chunks capped at 10 to 15 minutes
+- interactive activities such as quizzes, reflections, and simulations
+- formative assessments
+- explicit completion criteria
+
+### Recommendation engine
+
+- Matches learner profile vectors against module metadata vectors.
+- Combines content similarity with collaborative filtering signals.
+- Re-ranks recommendations based on progress, mastery, pacing, and risk.
+
+### Assessment and integrity
+
+- Builds unique question sets per learner from pools and AI-generated variants.
+- Supports scenario-based questions and open-ended tasks.
+- Uses time limits, randomization, plagiarism checks, and anomaly detection.
+
+### Learning analytics
+
+- Tracks time-on-task, interaction patterns, assessment performance, and progression paths.
+- Produces learner dashboards, dropout risk, success probability, and adaptive feedback.
+
+## 2. Scalable Architecture
+
+### Frontend
+
+- Web SPA for learners and admins.
+- Mobile app with sync support and notifications.
+
+### Backend services
+
+- `auth-service`
+- `profile-service`
+- `module-service`
+- `progress-service`
+- `assessment-service`
+- `recommendation-service`
+- `dashboard-service`
+- `notification-service`
+
+### AI and ML services
+
+- embedding generation service
+- recommendation ranker
+- AI question generation service
+- AI rubric evaluation service
+- plagiarism and anomaly detection engine
+- predictive analytics models
+
+### Data storage
+
+- PostgreSQL for learners, modules, assessments, and progress
+- NoSQL store for high-volume event logs
+- analytics warehouse for dashboards and modeling
+- vector index for learner/module semantic matching
+- object storage for assets, submissions, and artifacts
+
+## 3. Runtime Sequence
+
+### Registration to first recommendation
+
+1. Register learner and capture consent.
+2. Store learner intake data.
+3. Run diagnostic assessment.
+4. Build profile vector and readiness features.
+5. Rank starter modules.
+
+### Learning progression
+
+1. Learner consumes a content chunk.
+2. Progress and interaction events are captured.
+3. Analytics processor updates features.
+4. Recommendation engine refreshes next-best content or modules.
+
+### Assessment completion
+
+1. Assessment blueprint defines objectives and difficulty targets.
+2. Service assembles unique items per learner.
+3. Responses are graded using deterministic logic and AI rubric scoring.
+4. Integrity engine evaluates plagiarism and anomalies.
+5. Pass decision requires sufficient score, engagement, and integrity clearance.
+
+## 4. Scalability Notes
+
+- Stateless services behind autoscaling groups.
+- Event streaming for telemetry and downstream analytics.
+- Read/write separation to keep analytics off the transactional path.
+- Recommendation candidate generation can be precomputed; final ranking can run on demand.
+- AI-heavy tasks should be asynchronous where possible and fully audited.
+
+## 5. GDPR and Trust
+
+- Consent versioning and purpose-bound processing.
+- Pseudonymous analytics identifiers.
+- Right-to-access, deletion, correction, and portability support.
+- Human review for contested grading or high-stakes automated outcomes.
+- Clear model audit logs for recommendations and AI evaluation.

schemas/schema.sql

@@ -0,0 +1,271 @@
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+CREATE TABLE learners (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    first_name VARCHAR(100) NOT NULL,
+    last_name VARCHAR(100) NOT NULL,
+    locale VARCHAR(20) NOT NULL DEFAULT 'en-US',
+    timezone VARCHAR(64) NOT NULL,
+    educational_level VARCHAR(50) NOT NULL,
+    registration_status VARCHAR(30) NOT NULL DEFAULT 'active',
+    consent_personalization BOOLEAN NOT NULL DEFAULT FALSE,
+    consent_analytics BOOLEAN NOT NULL DEFAULT FALSE,
+    consent_version VARCHAR(50),
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    deleted_at TIMESTAMPTZ
+);
+
+CREATE TABLE learner_prior_learning (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    learning_type VARCHAR(20) NOT NULL CHECK (learning_type IN ('formal', 'non_formal', 'informal')),
+    title VARCHAR(255) NOT NULL,
+    provider VARCHAR(255),
+    description TEXT,
+    evidence_url TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE learner_goals (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    goal_horizon VARCHAR(20) NOT NULL CHECK (goal_horizon IN ('short_term', 'long_term')),
+    goal_text TEXT NOT NULL,
+    target_date DATE,
+    priority SMALLINT NOT NULL DEFAULT 3,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE learner_preferences (
+    learner_id UUID PRIMARY KEY REFERENCES learners(id),
+    preferred_modalities JSONB NOT NULL DEFAULT '[]'::jsonb,
+    preferred_session_length_minutes SMALLINT,
+    accessibility_needs JSONB NOT NULL DEFAULT '{}'::jsonb,
+    language_preferences JSONB NOT NULL DEFAULT '[]'::jsonb,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE learner_profiles (
+    learner_id UUID PRIMARY KEY REFERENCES learners(id),
+    readiness_level VARCHAR(30) NOT NULL,
+    readiness_score NUMERIC(5,2) NOT NULL,
+    competency_vector JSONB NOT NULL,
+    goal_vector JSONB NOT NULL,
+    profile_vector JSONB NOT NULL,
+    mastery_map JSONB NOT NULL,
+    risk_profile JSONB NOT NULL,
+    profile_version INTEGER NOT NULL DEFAULT 1,
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE modules (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    code VARCHAR(50) UNIQUE NOT NULL,
+    title VARCHAR(255) NOT NULL,
+    description TEXT NOT NULL,
+    ects_credits NUMERIC(4,1) NOT NULL DEFAULT 5.0,
+    difficulty_level VARCHAR(30) NOT NULL,
+    estimated_total_minutes INTEGER NOT NULL,
+    self_paced BOOLEAN NOT NULL DEFAULT TRUE,
+    adaptive_enabled BOOLEAN NOT NULL DEFAULT TRUE,
+    status VARCHAR(20) NOT NULL DEFAULT 'draft',
+    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
+    module_vector JSONB,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE module_objectives (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    objective_text TEXT NOT NULL,
+    bloom_level VARCHAR(30) NOT NULL,
+    competency_tag VARCHAR(100) NOT NULL,
+    measurable_outcome TEXT NOT NULL,
+    sort_order SMALLINT NOT NULL
+);
+
+CREATE TABLE module_units (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    title VARCHAR(255) NOT NULL,
+    unit_type VARCHAR(30) NOT NULL,
+    chunk_minutes SMALLINT NOT NULL CHECK (chunk_minutes BETWEEN 1 AND 15),
+    content_ref TEXT NOT NULL,
+    adaptive_rules JSONB NOT NULL DEFAULT '{}'::jsonb,
+    sort_order SMALLINT NOT NULL
+);
+
+CREATE TABLE module_activities (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    unit_id UUID REFERENCES module_units(id),
+    activity_type VARCHAR(30) NOT NULL,
+    title VARCHAR(255) NOT NULL,
+    instructions TEXT NOT NULL,
+    scoring_rubric JSONB,
+    max_score NUMERIC(6,2),
+    required BOOLEAN NOT NULL DEFAULT TRUE,
+    sort_order SMALLINT NOT NULL
+);
+
+CREATE TABLE module_completion_rules (
+    module_id UUID PRIMARY KEY REFERENCES modules(id),
+    min_unit_completion_ratio NUMERIC(5,2) NOT NULL,
+    min_formative_score NUMERIC(5,2) NOT NULL,
+    require_summative_pass BOOLEAN NOT NULL DEFAULT TRUE,
+    min_time_on_task_minutes INTEGER,
+    integrity_clearance_required BOOLEAN NOT NULL DEFAULT TRUE,
+    rules_json JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+
+CREATE TABLE module_prerequisites (
+    module_id UUID NOT NULL REFERENCES modules(id),
+    prerequisite_module_id UUID NOT NULL REFERENCES modules(id),
+    PRIMARY KEY (module_id, prerequisite_module_id)
+);
+
+CREATE TABLE assessments (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    assessment_type VARCHAR(30) NOT NULL CHECK (assessment_type IN ('diagnostic', 'formative', 'summative')),
+    title VARCHAR(255) NOT NULL,
+    blueprint JSONB NOT NULL,
+    time_limit_minutes INTEGER,
+    randomization_policy JSONB NOT NULL DEFAULT '{}'::jsonb,
+    integrity_policy JSONB NOT NULL DEFAULT '{}'::jsonb,
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE assessment_question_pool (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    assessment_id UUID NOT NULL REFERENCES assessments(id),
+    objective_id UUID REFERENCES module_objectives(id),
+    question_type VARCHAR(30) NOT NULL,
+    difficulty_band VARCHAR(20) NOT NULL,
+    prompt_template TEXT NOT NULL,
+    answer_key JSONB,
+    rubric JSONB,
+    tags JSONB NOT NULL DEFAULT '[]'::jsonb,
+    ai_generatable BOOLEAN NOT NULL DEFAULT FALSE,
+    active BOOLEAN NOT NULL DEFAULT TRUE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE assessment_attempts (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    assessment_id UUID NOT NULL REFERENCES assessments(id),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    started_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    submitted_at TIMESTAMPTZ,
+    duration_seconds INTEGER,
+    status VARCHAR(30) NOT NULL DEFAULT 'in_progress',
+    unique_question_set JSONB NOT NULL,
+    score NUMERIC(6,2),
+    pass_status VARCHAR(20),
+    integrity_status VARCHAR(20) NOT NULL DEFAULT 'pending',
+    ai_evaluation_trace JSONB,
+    anomaly_flags JSONB NOT NULL DEFAULT '[]'::jsonb
+);
+
+CREATE TABLE assessment_responses (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    attempt_id UUID NOT NULL REFERENCES assessment_attempts(id),
+    question_pool_id UUID REFERENCES assessment_question_pool(id),
+    prompt_snapshot TEXT NOT NULL,
+    response_payload JSONB NOT NULL,
+    auto_score NUMERIC(6,2),
+    ai_score NUMERIC(6,2),
+    final_score NUMERIC(6,2),
+    plagiarism_score NUMERIC(6,4),
+    feedback TEXT,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE enrollments (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    enrollment_status VARCHAR(30) NOT NULL DEFAULT 'active',
+    recommended_by VARCHAR(30) NOT NULL DEFAULT 'system',
+    started_at TIMESTAMPTZ,
+    completed_at TIMESTAMPTZ,
+    mastery_score NUMERIC(6,2),
+    UNIQUE (learner_id, module_id)
+);
+
+CREATE TABLE learner_progress (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    unit_id UUID REFERENCES module_units(id),
+    activity_id UUID REFERENCES module_activities(id),
+    progress_state VARCHAR(30) NOT NULL,
+    attempts_count INTEGER NOT NULL DEFAULT 0,
+    best_score NUMERIC(6,2),
+    time_on_task_seconds INTEGER NOT NULL DEFAULT 0,
+    last_interaction_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE interactions (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    module_id UUID REFERENCES modules(id),
+    unit_id UUID REFERENCES module_units(id),
+    activity_id UUID REFERENCES module_activities(id),
+    session_id UUID,
+    event_type VARCHAR(50) NOT NULL,
+    event_timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    duration_ms INTEGER,
+    payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+    client_context JSONB NOT NULL DEFAULT '{}'::jsonb
+);
+
+CREATE TABLE recommendation_impressions (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    module_id UUID NOT NULL REFERENCES modules(id),
+    rank_position INTEGER NOT NULL,
+    recommendation_reason JSONB NOT NULL DEFAULT '{}'::jsonb,
+    model_version VARCHAR(50) NOT NULL,
+    accepted BOOLEAN,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE TABLE analytics_daily_learner_metrics (
+    learner_id UUID NOT NULL REFERENCES learners(id),
+    metric_date DATE NOT NULL,
+    time_on_task_minutes NUMERIC(8,2) NOT NULL DEFAULT 0,
+    completed_units INTEGER NOT NULL DEFAULT 0,
+    formative_avg_score NUMERIC(6,2),
+    summative_pass_count INTEGER NOT NULL DEFAULT 0,
+    inactivity_days INTEGER NOT NULL DEFAULT 0,
+    dropout_risk NUMERIC(6,4),
+    success_probability NUMERIC(6,4),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (learner_id, metric_date)
+);
+
+CREATE TABLE analytics_model_audit_logs (
+    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+    learner_id UUID REFERENCES learners(id),
+    related_entity_type VARCHAR(50) NOT NULL,
+    related_entity_id UUID,
+    model_name VARCHAR(100) NOT NULL,
+    model_version VARCHAR(50) NOT NULL,
+    input_summary JSONB NOT NULL,
+    output_summary JSONB NOT NULL,
+    explanation TEXT,
+    human_review_required BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_interactions_learner_time ON interactions (learner_id, event_timestamp DESC);
+CREATE INDEX idx_progress_learner_module ON learner_progress (learner_id, module_id);
+CREATE INDEX idx_attempts_learner_assessment ON assessment_attempts (learner_id, assessment_id);
+CREATE INDEX idx_recommendation_impressions_learner ON recommendation_impressions (learner_id, created_at DESC);