# draco437/mirage architecture

> Architecture diagram of the GitHub repository draco437/mirage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/draco437/mirage
- Repository: https://github.com/draco437/mirage

## Overview

MIRAGE is a prototype adaptive social-skills platform: a therapist manages children and sessions, a Unity VR client streams session signals, and backend analysis can adapt the scene while reporting live results. The principal path runs from session telemetry through feature extraction, engagement inference and adaptation rules to Unity; therapists can also review analytics and override settings. The React entry point shown is still the Create React App placeholder, so it does not substantiate a dashboard UI. Some backend links are supported by the source index or module documentation rather than complete excerpts.

Main entry points: [`backend/ml_engine/tasks.py`](https://github.com/draco437/mirage/blob/main/backend/ml_engine/tasks.py) (Analysis Tasks), [`backend/core/consumers.py`](https://github.com/draco437/mirage/blob/main/backend/core/consumers.py) (Session Consumers), [`backend/core/views.py`](https://github.com/draco437/mirage/blob/main/backend/core/views.py) (REST API), [`backend/core/routing.py`](https://github.com/draco437/mirage/blob/main/backend/core/routing.py) (WebSocket Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Therapist API"]
  node_api_views["REST API<br/>[views.py]"]
  node_validation["Request Validation<br/>[serializers.py]"]
  node_web_app["Web App Placeholder<br/>[App.js]"]
end

subgraph group_realtime["Session Runtime"]
  node_ws_auth["WebSocket Auth<br/>[auth.py]"]
  node_ws_routes["WebSocket Routes<br/>[routing.py]"]
  node_ws_consumers["Session Consumers<br/>[consumers.py]"]
end

subgraph group_analysis["Adaptive Analysis"]
  node_celery_tasks["Analysis Tasks<br/>[tasks.py]"]
  node_feature_builder["Feature Extraction<br/>[features.py]"]
  node_emotion["Emotion Model<br/>[emotion_model.py]"]
  node_engagement["Engagement Model"]
  node_adaptation["Adaptation Rules"]
  node_fusion["Signal Fusion<br/>[fusion.py]"]
  node_signals["Signal Definitions<br/>[signals.py]"]
end

subgraph group_storage["Session Data"]
  node_mongo[("MongoDB<br/>[db.py]")]
end

subgraph group_training["Model Training"]
  node_synthetic["Synthetic Data"]
  node_training_job["Engagement Training"]
end

node_therapist(("Therapist"))
node_unity(("Unity VR Client"))

node_therapist -->|"manages sessions"| node_api_views
node_api_views -->|"validates requests"| node_validation
node_api_views -->|"reads and writes"| node_mongo
node_unity -->|"opens session socket"| node_ws_routes
node_ws_routes -->|"routes packets"| node_ws_consumers
node_ws_consumers -->|"checks connection auth"| node_ws_auth
node_ws_consumers -->|"validates packets"| node_validation
node_ws_consumers -->|"stores session events"| node_mongo
node_ws_consumers -->|"triggers analysis"| node_celery_tasks
node_celery_tasks -->|"reads and writes readings"| node_mongo
node_celery_tasks -->|"predicts emotion"| node_emotion
node_celery_tasks -->|"builds window features"| node_feature_builder
node_celery_tasks -->|"predicts engagement"| node_engagement
node_celery_tasks -->|"decides scene changes"| node_adaptation
node_celery_tasks -->|"pushes scene settings"| node_unity
node_celery_tasks -->|"pushes live updates"| node_therapist
node_api_views -->|"returns analytics"| node_therapist
node_therapist -->|"opens dashboard socket"| node_ws_routes
node_fusion -->|"uses signals"| node_signals
node_synthetic -->|"uses feature schema"| node_feature_builder
node_training_job -->|"uses generated data"| node_synthetic
node_training_job -->|"uses feature schema"| node_feature_builder

click node_api_views "https://github.com/draco437/mirage/blob/main/backend/core/views.py"
click node_validation "https://github.com/draco437/mirage/blob/main/backend/core/serializers.py"
click node_ws_auth "https://github.com/draco437/mirage/blob/main/backend/core/auth.py"
click node_ws_routes "https://github.com/draco437/mirage/blob/main/backend/core/routing.py"
click node_ws_consumers "https://github.com/draco437/mirage/blob/main/backend/core/consumers.py"
click node_celery_tasks "https://github.com/draco437/mirage/blob/main/backend/ml_engine/tasks.py"
click node_feature_builder "https://github.com/draco437/mirage/blob/main/backend/ml_engine/features.py"
click node_emotion "https://github.com/draco437/mirage/blob/main/backend/ml_engine/emotion_model.py"
click node_engagement "https://github.com/draco437/mirage/blob/main/backend/ml_engine/engagement_model.py"
click node_adaptation "https://github.com/draco437/mirage/blob/main/backend/ml_engine/adaptation_rules.py"
click node_fusion "https://github.com/draco437/mirage/blob/main/backend/ml_engine/fusion.py"
click node_signals "https://github.com/draco437/mirage/blob/main/backend/ml_engine/signals.py"
click node_mongo "https://github.com/draco437/mirage/blob/main/backend/db.py"
click node_synthetic "https://github.com/draco437/mirage/blob/main/backend/ml_training/generate_synthetic.py"
click node_training_job "https://github.com/draco437/mirage/blob/main/backend/ml_training/train_engagement_rf.py"
click node_web_app "https://github.com/draco437/mirage/blob/main/frontend/src/App.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_views,node_validation,node_web_app,node_unity toneBlue
class node_ws_auth,node_ws_routes,node_ws_consumers toneAmber
class node_celery_tasks,node_feature_builder,node_emotion,node_engagement,node_adaptation,node_fusion,node_signals,node_therapist toneMint
class node_mongo toneRose
class node_synthetic,node_training_job toneIndigo
```

## Components

### Therapist API

- [REST API](https://github.com/draco437/mirage/blob/main/backend/core/views.py): `backend/core/views.py`
- [Request Validation](https://github.com/draco437/mirage/blob/main/backend/core/serializers.py): `backend/core/serializers.py`
- [Web App Placeholder](https://github.com/draco437/mirage/blob/main/frontend/src/App.js): `frontend/src/App.js`

### Session Runtime

- [WebSocket Auth](https://github.com/draco437/mirage/blob/main/backend/core/auth.py): `backend/core/auth.py`
- [WebSocket Routes](https://github.com/draco437/mirage/blob/main/backend/core/routing.py): `backend/core/routing.py`
- [Session Consumers](https://github.com/draco437/mirage/blob/main/backend/core/consumers.py): `backend/core/consumers.py`

### Adaptive Analysis

- [Analysis Tasks](https://github.com/draco437/mirage/blob/main/backend/ml_engine/tasks.py): `backend/ml_engine/tasks.py`
- [Feature Extraction](https://github.com/draco437/mirage/blob/main/backend/ml_engine/features.py): `backend/ml_engine/features.py`
- [Emotion Model](https://github.com/draco437/mirage/blob/main/backend/ml_engine/emotion_model.py): `backend/ml_engine/emotion_model.py`
- [Engagement Model](https://github.com/draco437/mirage/blob/main/backend/ml_engine/engagement_model.py): `backend/ml_engine/engagement_model.py`
- [Adaptation Rules](https://github.com/draco437/mirage/blob/main/backend/ml_engine/adaptation_rules.py): `backend/ml_engine/adaptation_rules.py`
- [Signal Fusion](https://github.com/draco437/mirage/blob/main/backend/ml_engine/fusion.py): `backend/ml_engine/fusion.py`
- [Signal Definitions](https://github.com/draco437/mirage/blob/main/backend/ml_engine/signals.py): `backend/ml_engine/signals.py`

### Session Data

- [MongoDB](https://github.com/draco437/mirage/blob/main/backend/db.py): `backend/db.py`

### Model Training

- [Synthetic Data](https://github.com/draco437/mirage/blob/main/backend/ml_training/generate_synthetic.py): `backend/ml_training/generate_synthetic.py`
- [Engagement Training](https://github.com/draco437/mirage/blob/main/backend/ml_training/train_engagement_rf.py): `backend/ml_training/train_engagement_rf.py`

### Other components

- **Therapist**
- **Unity VR Client**

## Connections

- Therapist → REST API: manages sessions (evidence: `backend/core/views.py`)
- REST API → Request Validation: validates requests (evidence: `backend/core/views.py`)
- REST API → MongoDB: reads and writes (evidence: `backend/core/views.py`)
- Unity VR Client → WebSocket Routes: opens session socket (evidence: `backend/core/routing.py`)
- WebSocket Routes → Session Consumers: routes packets (evidence: `backend/core/routing.py`)
- Session Consumers → WebSocket Auth: checks connection auth
- Session Consumers → Request Validation: validates packets (evidence: `backend/core/consumers.py`)
- Session Consumers → MongoDB: stores session events (evidence: `backend/core/consumers.py`)
- Session Consumers → Analysis Tasks: triggers analysis (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → MongoDB: reads and writes readings (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → Emotion Model: predicts emotion (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → Feature Extraction: builds window features (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → Engagement Model: predicts engagement (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → Adaptation Rules: decides scene changes (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → Unity VR Client: pushes scene settings (evidence: `backend/ml_engine/tasks.py`)
- Analysis Tasks → Therapist: pushes live updates (evidence: `backend/ml_engine/tasks.py`)
- REST API → Therapist: returns analytics (evidence: `backend/core/views.py`)
- Therapist → WebSocket Routes: opens dashboard socket (evidence: `backend/core/routing.py`)
- Signal Fusion → Signal Definitions: uses signals (evidence: `backend/ml_engine/fusion.py`)
- Synthetic Data → Feature Extraction: uses feature schema (evidence: `backend/ml_training/generate_synthetic.py`)
- Engagement Training → Synthetic Data: uses generated data (evidence: `backend/ml_training/train_engagement_rf.py`)
- Engagement Training → Feature Extraction: uses feature schema (evidence: `backend/ml_training/train_engagement_rf.py`)