# med-air/medgame architecture

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

- Interactive diagram: https://gitdiagram.com/med-air/medgame
- Repository: https://github.com/med-air/medgame

## Overview

MedGAME turns clinical summaries into structured, interactive medical-education stories, then generates multimodal story assets for learners to play through acts, scenes, and question interactions. The pipeline has distinct narrative-design, story-direction, and audio/video-execution stages; the UI serves generated case content and tracks player progress. The UI/API flow and selected services are sampled; other endpoint-to-service wiring and parts of the generation pipeline are described only in the README, so uncertain connections are omitted.

Main entry points: [`MedGAME_UI/Frontend/src/stores/gameStore.ts`](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/stores/gameStore.ts) (Game state), [`MedGAME_UI/Frontend/src/pages/GamePage.tsx`](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/pages/GamePage.tsx) (Game screen), [`MedGAME_UI/BackEnd/app/api/router.py`](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/api/router.py) (API routes), [`MedGAME_UI/BackEnd/app/services/scene_service.py`](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/scene_service.py) (Scene media)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Story generation"]
  node_designer["Narrative designer"]
  node_story_schema["Story schema<br/>[pydantic_models.py]"]
  node_story_director["Story director<br/>[movie_builder.py]"]
  node_audio_execution["Audio generation"]
  node_video_execution["Video generation"]
end

subgraph group_backend["Game backend"]
  node_app_entry["FastAPI entry<br/>[main.py]"]
  node_api_router["API routes<br/>[router.py]"]
  node_case_service["Case loading<br/>[case_service.py]"]
  node_scene_service["Scene media<br/>[scene_service.py]"]
  node_subtitle_service["Subtitle parsing"]
  node_case_files["Case files"]
end

subgraph group_frontend["Player experience"]
  node_frontend_app["UI routes<br/>[App.tsx]"]
  node_home_page["Case selection<br/>[HomePage.tsx]"]
  node_game_page["Game screen<br/>[GamePage.tsx]"]
  node_game_store["Game state<br/>[gameStore.ts]"]
  node_api_client["HTTP client<br/>[client.ts]"]
  node_interactions["Question interactions"]
  node_media_display["Story presentation"]
end

subgraph group_state["Player state"]
  node_player_service["Progress service<br/>[player_service.py]"]
  node_player_state["Progress records<br/>[player_service.py]"]
end

node_learner(("Learner"))
node_patient_summary["Patient summary"]
node_generated_assets["Story assets"]

node_patient_summary -->|"provides input"| node_designer
node_designer -->|"constrains output"| node_story_schema
node_designer -->|"passes storyline"| node_story_director
node_story_director -->|"plans tasks"| node_audio_execution
node_story_director -->|"plans tasks"| node_video_execution
node_audio_execution -->|"generates audio"| node_generated_assets
node_video_execution -->|"generates video"| node_generated_assets
node_generated_assets -.->|"materializes as"| node_case_files
node_learner -->|"selects case"| node_home_page
node_frontend_app -->|"routes to"| node_home_page
node_frontend_app -->|"routes to"| node_game_page
node_home_page -->|"starts case"| node_game_store
node_game_page -->|"reads game state"| node_game_store
node_game_store -->|"requests data"| node_api_client
node_api_client -->|"sends HTTP"| node_app_entry
node_app_entry -->|"registers routes"| node_api_router
node_api_router -->|"dispatches case routes"| node_case_service
node_api_router -->|"dispatches game routes"| node_scene_service
node_api_router -->|"dispatches player routes"| node_player_service
node_case_service -->|"reads case data"| node_case_files
node_scene_service -->|"reads scene media"| node_case_files
node_scene_service -->|"parses subtitles"| node_subtitle_service
node_scene_service -->|"returns scene media"| node_game_store
node_case_service -->|"returns story data"| node_game_store
node_game_store -->|"updates view state"| node_game_page
node_game_page -->|"presents narrative"| node_media_display
node_game_page -->|"presents questions"| node_interactions
node_learner -->|"answers questions"| node_interactions
node_player_service -->|"stores progress"| node_player_state

click node_designer "https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/generation_factory.py"
click node_story_schema "https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/pydantic_models.py"
click node_story_director "https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/movie_builder.py"
click node_audio_execution "https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/audio_video_pipeline.py"
click node_video_execution "https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/infinitetalk_runner.py"
click node_app_entry "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/main.py"
click node_api_router "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/api/router.py"
click node_case_service "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/case_service.py"
click node_scene_service "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/scene_service.py"
click node_subtitle_service "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/subtitle_service.py"
click node_player_service "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/player_service.py"
click node_frontend_app "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/App.tsx"
click node_home_page "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/pages/HomePage.tsx"
click node_game_page "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/pages/GamePage.tsx"
click node_game_store "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/stores/gameStore.ts"
click node_api_client "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/api/client.ts"
click node_interactions "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/components/interaction/InteractionContainer.tsx"
click node_media_display "https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/components/common/ImmersiveDialogueDisplay.tsx"
click node_player_state "https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/player_service.py"

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_designer,node_story_schema,node_story_director,node_audio_execution,node_video_execution toneBlue
class node_app_entry,node_api_router,node_case_service,node_scene_service,node_subtitle_service,node_case_files toneAmber
class node_frontend_app,node_home_page,node_game_page,node_game_store,node_api_client,node_interactions,node_media_display toneMint
class node_player_service,node_player_state toneRose
class node_learner,node_patient_summary,node_generated_assets toneIndigo
```

## Components

### Story generation

- [Narrative designer](https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/generation_factory.py): `MedGame_Pipeline/generation_factory.py`
- [Story schema](https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/pydantic_models.py): `MedGame_Pipeline/pydantic_models.py`
- [Story director](https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/movie_builder.py): `MedGame_Pipeline/movie_builder.py`
- [Audio generation](https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/audio_video_pipeline.py): `MedGame_Pipeline/audio_video_pipeline.py`
- [Video generation](https://github.com/med-air/medgame/blob/main/MedGame_Pipeline/infinitetalk_runner.py): `MedGame_Pipeline/infinitetalk_runner.py`

### Game backend

- [FastAPI entry](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/main.py): `MedGAME_UI/BackEnd/app/main.py`
- [API routes](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/api/router.py): `MedGAME_UI/BackEnd/app/api/router.py`
- [Case loading](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/case_service.py): `MedGAME_UI/BackEnd/app/services/case_service.py`
- [Scene media](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/scene_service.py): `MedGAME_UI/BackEnd/app/services/scene_service.py`
- [Subtitle parsing](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/subtitle_service.py): `MedGAME_UI/BackEnd/app/services/subtitle_service.py`
- **Case files**

### Player experience

- [UI routes](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/App.tsx): `MedGAME_UI/Frontend/src/App.tsx`
- [Case selection](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/pages/HomePage.tsx): `MedGAME_UI/Frontend/src/pages/HomePage.tsx`
- [Game screen](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/pages/GamePage.tsx): `MedGAME_UI/Frontend/src/pages/GamePage.tsx`
- [Game state](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/stores/gameStore.ts): `MedGAME_UI/Frontend/src/stores/gameStore.ts`
- [HTTP client](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/api/client.ts): `MedGAME_UI/Frontend/src/api/client.ts`
- [Question interactions](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/components/interaction/InteractionContainer.tsx): `MedGAME_UI/Frontend/src/components/interaction/InteractionContainer.tsx`
- [Story presentation](https://github.com/med-air/medgame/blob/main/MedGAME_UI/Frontend/src/components/common/ImmersiveDialogueDisplay.tsx): `MedGAME_UI/Frontend/src/components/common/ImmersiveDialogueDisplay.tsx`

### Player state

- [Progress service](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/player_service.py): `MedGAME_UI/BackEnd/app/services/player_service.py`
- [Progress records](https://github.com/med-air/medgame/blob/main/MedGAME_UI/BackEnd/app/services/player_service.py): `MedGAME_UI/BackEnd/app/services/player_service.py`

### Other components

- **Learner**
- **Patient summary**
- **Story assets**

## Connections

- Patient summary → Narrative designer: provides input
- Narrative designer → Story schema: constrains output
- Narrative designer → Story director: passes storyline
- Story director → Audio generation: plans tasks
- Story director → Video generation: plans tasks
- Audio generation → Story assets: generates audio
- Video generation → Story assets: generates video
- Story assets → Case files: materializes as
- Learner → Case selection: selects case
- UI routes → Case selection: routes to
- UI routes → Game screen: routes to
- Case selection → Game state: starts case
- Game screen → Game state: reads game state
- Game state → HTTP client: requests data
- HTTP client → FastAPI entry: sends HTTP
- FastAPI entry → API routes: registers routes
- API routes → Case loading: dispatches case routes
- API routes → Scene media: dispatches game routes
- API routes → Progress service: dispatches player routes
- Case loading → Case files: reads case data
- Scene media → Case files: reads scene media
- Scene media → Subtitle parsing: parses subtitles
- Scene media → Game state: returns scene media
- Case loading → Game state: returns story data
- Game state → Game screen: updates view state
- Game screen → Story presentation: presents narrative
- Game screen → Question interactions: presents questions
- Learner → Question interactions: answers questions
- Progress service → Progress records: stores progress