wip

figures/architecture.mmd

@@ -0,0 +1,48 @@
+flowchart LR
+  %% Clients (Frontends)
+  subgraph Clients["Clients (Frontends)"]
+    SC["Spiel-Client"]
+    DC["Dashboard-Client"]
+  end
+
+  %% Ingestion
+  subgraph Ingestion["Telemetry Ingestion"]
+    CG["Consent-Gate"]
+    COL["Collector<br/>(Auth + Schema-Validation)"]
+  end
+
+  %% Separation
+  subgraph Streams["Trennung der Datenströme"]
+    DID["Didaktik-Stream<br/>(Lern/Verhalten)"]
+    SYS["System-Stream<br/>(Fehler/Performance)"]
+  end
+
+  %% Storage
+  subgraph Storage["Persistenz"]
+    LRS["LRS / Event Store<br/>(Rohdaten)"]
+  end
+
+  %% Analytics
+  subgraph Analytics["Analytics"]
+    AGG["Aggregation<br/>(KPIs/Indikatoren)"]
+    ADB["Analytics DB<br/>(Serving Layer)"]
+  end
+
+  %% Governance
+  subgraph Gov["Governance"]
+    RB["RBAC/ABAC"]
+    RET["Retention/Löschung"]
+    AUD["Audit Logs"]
+  end
+
+  %% Flows
+  SC --> CG --> COL
+  COL --> DID --> LRS
+  COL --> SYS --> LRS
+  LRS --> AGG --> ADB --> DC
+
+  %% Governance as controls
+  RB -. "Zugriff" .-> LRS
+  RB -. "Zugriff" .-> ADB
+  RET -. "Regeln" .-> LRS
+  AUD <-. "Zugriffe/Exporte" .-> DC

figures/dataflow-and-governance.mmd

@@ -0,0 +1,51 @@
+flowchart LR
+  %% High-level dataflow for telemetry in serious games with governance controls
+
+  subgraph C["Client / Spiel"]
+    U["Lernende:r"]
+    CG["Consent-Gate<br/>(Opt-in/Policy-Version)"]
+    EL["Event Logger<br/>(Batching/Offline-Queue)"]
+    U --> CG --> EL
+  end
+
+  subgraph I["Ingestion"]
+    COL["Telemetry Collector<br/>(Auth, Schema-Validation, Rate-Limits)"]
+  end
+
+  subgraph G["Governance & Identitätstrennung"]
+    PID["Pseudonymisierungs-/Mapping-Service<br/>(getrennte Identitätsdomäne)"]
+    RB["RBAC/ABAC Policy Engine"]
+    AUD["Audit Logs<br/>(Zugriffe/Exporte)"]
+  end
+
+  subgraph S["Persistenz"]
+    LRS["LRS / Event Store<br/>(Rohdaten/Lernspur)"]
+  end
+
+  subgraph A["Analytics"]
+    ETL["ETL/ELT & Qualitätschecks<br/>(Dedupe, Missing Data, Drift)"]
+    AGG["Aggregation<br/>(KPIs, Zeitfenster, Kohorten)"]
+    ADB["Analytics DB<br/>(materialisierte Sichten)"]
+  end
+
+  subgraph R["Reporting"]
+    DASH["Dashboard/Reports<br/>(Filter, Drilldown, Exporte)"]
+    ST["Stakeholder<br/>(z. B. Lehrkraft/Trainer:in)"]
+  end
+
+  %% Main flow
+  EL --> COL
+  COL --> PID
+  PID --> LRS
+  LRS --> ETL --> AGG --> ADB --> DASH --> ST
+
+  %% Governance controls
+  RB -. "Zugriffskontrolle" .-> LRS
+  RB -. "Zugriffskontrolle" .-> ADB
+  RB -. "Zugriffskontrolle" .-> DASH
+  DASH --> AUD
+  LRS --> AUD
+  ADB --> AUD
+
+  %% Data separation hint
+  COL -. "Trennung: technisch vs. didaktisch" .- PID

figures/feedback-loop.mmd

@@ -0,0 +1,11 @@
+flowchart LR
+  T["Telemetrie<br/>(Events/Statements)"] --> A["Analytics<br/>(KPIs/Indikatoren)"]
+
+  A --> IG["In-Game Feedback<br/>(Hints/Erklärungen)"]
+  A --> DB["Dashboard<br/>(Übersicht/Drilldown)"]
+
+  DB --> INT["Intervention<br/>(z. B. Unterstützung/Anpassung)"]
+
+  %% Rückkopplung: Feedback/Intervention verändert Verhalten und erzeugt neue Telemetrie
+  IG -. "beeinflusst" .-> T
+  INT -. "beeinflusst" .-> T

figures/metrics-and-indicators.mmd

@@ -0,0 +1,17 @@
+flowchart LR
+  LZ["Lernziel / Kompetenz"]
+  IND["Beobachtbarer Indikator<br/>(Outcome + Prozess)"]
+  EVT["Event / Statement<br/>(z. B. xAPI oder Custom)"]
+  MET["Metrik / KPI<br/>(Formel + Zeitfenster)"]
+  OUT["Dashboard / Feedback / Intervention<br/>(Entscheidungsunterstützung)"]
+
+  LZ --> IND --> EVT --> MET --> OUT
+
+  %% Governance & Qualität als Querschnitt
+  GOV["Governance<br/>(Zweckbindung, Minimierung, RBAC, Retention)"]
+  QUAL["Datenqualität<br/>(Schema, Versionierung, Drift, Missing Data)"]
+
+  GOV -. "steuert" .-> EVT
+  GOV -. "steuert" .-> MET
+  QUAL -. "prüft" .-> EVT
+  QUAL -. "prüft" .-> MET

figures/xapi-schema.mmd

@@ -0,0 +1,17 @@
+flowchart TB
+  subgraph S["xAPI Statement"]
+    A["Actor<br/>(Agent/Group)"]
+    V["Verb<br/>(URI + display)"]
+    O["Object<br/>(Activity/Agent/StatementRef)"]
+    R["Result<br/>(success, score, duration, response*)"]
+    C["Context<br/>(activity context, group, platform, instructor*, contextActivities, registration, extensions)"]
+    T["Timestamp<br/>(event time)"]
+    X["Extensions<br/>(custom fields in allowed locations)"]
+  end
+
+  A --> V --> O
+  O --> R
+  O --> C
+  O --> T
+  R -. "optional" .-> X
+  C -. "optional" .-> X