# mynameisyera/ustaz-phy architecture

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

- Interactive diagram: https://gitdiagram.com/mynameisyera/ustaz-phy
- Repository: https://github.com/mynameisyera/ustaz-phy

## Overview

Ustaz is an educational platform combining subject labs and interactive simulations with a game studio for generating, refining, launching, and exporting games. The sampled frontend shows route selection, service setup, and the studio’s use of game operations; the sampled server shows API dispatch to material-extraction and game-generation handlers. The tree also documents templates, subject-specific labs, and simulator implementations, but their internal wiring was not sampled, so those branches are represented without speculative connections.

Main entry points: [`src/presentation/hooks/useGameStudio.ts`](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/hooks/useGameStudio.ts) (Game studio UI), [`src/App.tsx`](https://github.com/mynameisyera/ustaz-phy/blob/main/src/App.tsx) (Route entry), [`server/app.ts`](https://github.com/mynameisyera/ustaz-phy/blob/main/server/app.ts) (API application), [`src/presentation/context/ServicesContext.tsx`](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/context/ServicesContext.tsx) (Service context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["App and studio"]
  node_app["Route entry<br/>[App.tsx]"]
  node_ustaz["Ustaz interface<br/>[UstazApp.tsx]"]
  node_studio["Game studio UI<br/>[useGameStudio.ts]"]
  node_services["Service context"]
end

subgraph group_game["Game lifecycle"]
  node_create["Game creation<br/>[CreateGame.ts]"]
  node_fix["Game fixes<br/>[ApplyFix.ts]"]
  node_launch["Game launch<br/>[LaunchGame.ts]"]
  node_export["Game export<br/>[ExportGame.ts]"]
  node_games[("Game records")]
  node_generator["HTTP generator"]
  node_launcher["Blob launcher"]
  node_zip["ZIP exporter<br/>[ZipGameExporter.ts]"]
end

subgraph group_labs["Subject labs"]
  node_labsui["Subject lab pages<br/>[LabsPage.tsx]"]
  node_labgames["Lab game loading<br/>[useLabGames.tsx]"]
  node_labsapi["Labs API client<br/>[LabsApi.ts]"]
  node_physics["Physics simulators"]
  node_geogebra["GeoGebra activities"]
  node_geography["Geography maps<br/>[MapEngine.tsx]"]
  node_templates["Game templates"]
end

subgraph group_server["AI API"]
  node_api["API application<br/>[app.ts]"]
  node_extract["Material extraction"]
  node_generate["Game generation<br/>[handleGenerate.ts]"]
  node_pdf["PDF extraction"]
  node_ai["AI provider<br/>[ai.ts]"]
end

node_learner(("Learner"))

node_learner -->|"opens"| node_app
node_app -->|"routes default"| node_ustaz
node_app -->|"provides services"| node_services
node_services -->|"supplies operations"| node_studio
node_studio -->|"creates game"| node_create
node_studio -->|"submits fix"| node_fix
node_studio -->|"launches game"| node_launch
node_studio -->|"exports game"| node_export
node_studio -->|"loads game"| node_games
node_labgames -->|"fetches labs"| node_labsapi
node_api -->|"dispatches extraction"| node_extract
node_api -->|"dispatches generation"| node_generate

click node_app "https://github.com/mynameisyera/ustaz-phy/blob/main/src/App.tsx"
click node_ustaz "https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/components/ustaz/UstazApp.tsx"
click node_studio "https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/hooks/useGameStudio.ts"
click node_services "https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/context/ServicesContext.tsx"
click node_create "https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/CreateGame.ts"
click node_fix "https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/ApplyFix.ts"
click node_launch "https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/LaunchGame.ts"
click node_export "https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/ExportGame.ts"
click node_games "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/repositories/InMemoryGameRepository.ts"
click node_generator "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/generators/HttpGameGenerator.ts"
click node_launcher "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/launchers/BlobGameLauncher.ts"
click node_zip "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/exporters/ZipGameExporter.ts"
click node_labsui "https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/components/ustaz/LabsPage.tsx"
click node_labgames "https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/hooks/useLabGames.tsx"
click node_labsapi "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/labs/LabsApi.ts"
click node_physics "https://github.com/mynameisyera/ustaz-phy/tree/main/src/presentation/components/simulators"
click node_geogebra "https://github.com/mynameisyera/ustaz-phy/tree/main/src/infrastructure/geogebra"
click node_geography "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/geography/MapEngine.tsx"
click node_templates "https://github.com/mynameisyera/ustaz-phy/tree/main/src/infrastructure/templates"
click node_api "https://github.com/mynameisyera/ustaz-phy/blob/main/server/app.ts"
click node_extract "https://github.com/mynameisyera/ustaz-phy/blob/main/server/handleExtractMaterial.ts"
click node_generate "https://github.com/mynameisyera/ustaz-phy/blob/main/server/handleGenerate.ts"
click node_pdf "https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/pdf/extractPdfMaterial.ts"
click node_ai "https://github.com/mynameisyera/ustaz-phy/blob/main/server/ai.ts"

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_app,node_ustaz,node_studio,node_services toneBlue
class node_create,node_fix,node_launch,node_export,node_games,node_generator,node_launcher,node_zip toneAmber
class node_labsui,node_labgames,node_labsapi,node_physics,node_geogebra,node_geography,node_templates toneMint
class node_api,node_extract,node_generate,node_pdf,node_ai toneRose
class node_learner toneIndigo
```

## Components

### App and studio

- [Route entry](https://github.com/mynameisyera/ustaz-phy/blob/main/src/App.tsx): `src/App.tsx`
- [Ustaz interface](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/components/ustaz/UstazApp.tsx): `src/presentation/components/ustaz/UstazApp.tsx`
- [Game studio UI](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/hooks/useGameStudio.ts): `src/presentation/hooks/useGameStudio.ts`
- [Service context](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/context/ServicesContext.tsx): `src/presentation/context/ServicesContext.tsx`

### Game lifecycle

- [Game creation](https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/CreateGame.ts): `src/domain/usecases/CreateGame.ts`
- [Game fixes](https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/ApplyFix.ts): `src/domain/usecases/ApplyFix.ts`
- [Game launch](https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/LaunchGame.ts): `src/domain/usecases/LaunchGame.ts`
- [Game export](https://github.com/mynameisyera/ustaz-phy/blob/main/src/domain/usecases/ExportGame.ts): `src/domain/usecases/ExportGame.ts`
- [Game records](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/repositories/InMemoryGameRepository.ts): `src/infrastructure/repositories/InMemoryGameRepository.ts`
- [HTTP generator](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/generators/HttpGameGenerator.ts): `src/infrastructure/generators/HttpGameGenerator.ts`
- [Blob launcher](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/launchers/BlobGameLauncher.ts): `src/infrastructure/launchers/BlobGameLauncher.ts`
- [ZIP exporter](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/exporters/ZipGameExporter.ts): `src/infrastructure/exporters/ZipGameExporter.ts`

### Subject labs

- [Subject lab pages](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/components/ustaz/LabsPage.tsx): `src/presentation/components/ustaz/LabsPage.tsx`
- [Lab game loading](https://github.com/mynameisyera/ustaz-phy/blob/main/src/presentation/hooks/useLabGames.tsx): `src/presentation/hooks/useLabGames.tsx`
- [Labs API client](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/labs/LabsApi.ts): `src/infrastructure/labs/LabsApi.ts`
- [Physics simulators](https://github.com/mynameisyera/ustaz-phy/tree/main/src/presentation/components/simulators): `src/presentation/components/simulators`
- [GeoGebra activities](https://github.com/mynameisyera/ustaz-phy/tree/main/src/infrastructure/geogebra): `src/infrastructure/geogebra`
- [Geography maps](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/geography/MapEngine.tsx): `src/infrastructure/geography/MapEngine.tsx`
- [Game templates](https://github.com/mynameisyera/ustaz-phy/tree/main/src/infrastructure/templates): `src/infrastructure/templates`

### AI API

- [API application](https://github.com/mynameisyera/ustaz-phy/blob/main/server/app.ts): `server/app.ts`
- [Material extraction](https://github.com/mynameisyera/ustaz-phy/blob/main/server/handleExtractMaterial.ts): `server/handleExtractMaterial.ts`
- [Game generation](https://github.com/mynameisyera/ustaz-phy/blob/main/server/handleGenerate.ts): `server/handleGenerate.ts`
- [PDF extraction](https://github.com/mynameisyera/ustaz-phy/blob/main/src/infrastructure/pdf/extractPdfMaterial.ts): `src/infrastructure/pdf/extractPdfMaterial.ts`
- [AI provider](https://github.com/mynameisyera/ustaz-phy/blob/main/server/ai.ts): `server/ai.ts`

### Other components

- **Learner**

## Connections

- Learner → Route entry: opens
- Route entry → Ustaz interface: routes default
- Route entry → Service context: provides services
- Service context → Game studio UI: supplies operations
- Game studio UI → Game creation: creates game
- Game studio UI → Game fixes: submits fix
- Game studio UI → Game launch: launches game
- Game studio UI → Game export: exports game
- Game studio UI → Game records: loads game
- Lab game loading → Labs API client: fetches labs
- API application → Material extraction: dispatches extraction
- API application → Game generation: dispatches generation