# huseyinsihat/ufkumuzyildizlar architecture

> Architecture diagram of the GitHub repository huseyinsihat/ufkumuzyildizlar, 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/huseyinsihat/ufkumuzyildizlar
- Repository: https://github.com/huseyinsihat/ufkumuzyildizlar

## Overview

Ufkumuz Yıldızlar is a bilingual, browser-based astronomy learning app: learners explore a simulated solar system, control its time and viewpoint, and enter guided activities, while also discovering sky events or asking the Sun questions. The graph highlights the UI entry point, simulation and rendering, education and events, and optional hardware, voice, and AI integrations. The README documents the Deneyap controls; sampled code confirms app wiring, lab-to-scene control, and event scheduling. Other subsystem links are kept at documented capability level where implementation excerpts were unavailable.

Main entry points: [`src/App.tsx`](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/App.tsx) (App Shell), [`src/scene/SolarSystemScene.ts`](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/SolarSystemScene.ts) (Solar System Scene), [`src/store/labStore.ts`](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/store/labStore.ts) (Lab State), [`src/components/lab/ActivityBody.tsx`](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/lab/ActivityBody.tsx) (Activity UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application UI"]
  node_app["App Shell<br/>[App.tsx]"]
  node_explore["Explore Controls<br/>[PlanetDrawer.tsx]"]
  node_chatpanel["Sun Chat Panel<br/>[SunChatPanel.tsx]"]
  node_labui["Activity UI<br/>[ActivityBody.tsx]"]
end

subgraph group_simulation["Simulation and Scene"]
  node_canvas["3D Canvas Host<br/>[CanvasHost.tsx]"]
  node_fallback["2D Fallback<br/>[SolarSystem2D.tsx]"]
  node_scene["Solar System Scene"]
  node_camera["Camera Controller"]
  node_sceneapi["Scene API<br/>[sceneApi.ts]"]
  node_simstore["Simulation State<br/>[simulationStore.ts]"]
  node_eventlayer["Event Visual Layer<br/>[AstroEventLayer.ts]"]
end

subgraph group_learning["Learning Features"]
  node_labhome["Lab Home<br/>[LabHome.tsx]"]
  node_labstore["Lab State<br/>[labStore.ts]"]
  node_activities["Lab Activities<br/>[labActivities.ts]"]
  node_education["Education Panels<br/>[EducationHub.tsx]"]
  node_events["Event Scheduler"]
  node_eventdata["Event Content<br/>[astroEvents.ts]"]
end

subgraph group_integrations["Optional Integrations"]
  node_hardware["Hardware Controls<br/>[HardwarePanel.tsx]"]
  node_hardwarestore["Hardware Store<br/>[hardwareStore.ts]"]
  node_voice["Voice Host<br/>[VoiceHost.tsx]"]
  node_chatfeature["Chat Completion<br/>[openRouter.ts]"]
end

subgraph group_domain["Astronomy Domain"]
  node_time["Time Engine<br/>[timeEngine.ts]"]
  node_astro["Astronomy Calculations"]
  node_planets["Planet Data<br/>[planetData.ts]"]
end

node_learner(("Learner"))
node_device["Deneyap Card"]
node_openrouter["OpenRouter Service"]

node_learner -->|"uses"| node_app
node_app -->|"renders"| node_explore
node_app -->|"renders"| node_chatpanel
node_app -->|"renders"| node_labui
node_app -->|"renders"| node_canvas
node_app -->|"renders"| node_fallback
node_app -->|"renders"| node_labhome
node_app -->|"renders"| node_education
node_app -->|"renders"| node_hardware
node_app -->|"renders"| node_voice
node_app -->|"starts"| node_events
node_canvas -->|"hosts"| node_scene
node_scene -->|"controls view"| node_camera
node_labui -->|"updates"| node_labstore
node_labui -->|"reads"| node_activities
node_labstore -->|"controls scene"| node_sceneapi
node_labstore -->|"updates"| node_simstore
node_labstore -->|"reads"| node_activities
node_scene -->|"uses calculations"| node_astro
node_scene -->|"reads data"| node_planets
node_events -->|"schedules from"| node_eventdata
node_events -->|"dispatches events"| node_eventlayer
node_app -->|"watches ports"| node_hardwarestore
node_hardware -->|"controls"| node_hardwarestore
node_hardwarestore -.->|"communicates"| node_device
node_chatpanel -.->|"requests replies"| node_chatfeature
node_chatfeature -.->|"sends chat"| node_openrouter
node_simstore -->|"uses time scale"| node_time

click node_app "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/App.tsx"
click node_explore "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/ui/PlanetDrawer.tsx"
click node_chatpanel "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/chat/SunChatPanel.tsx"
click node_labui "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/lab/ActivityBody.tsx"
click node_canvas "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/3d/CanvasHost.tsx"
click node_fallback "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/3d/SolarSystem2D.tsx"
click node_scene "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/SolarSystemScene.ts"
click node_camera "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/CameraController.ts"
click node_sceneapi "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/sceneApi.ts"
click node_simstore "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/store/simulationStore.ts"
click node_time "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/astronomy/timeEngine.ts"
click node_astro "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/astronomy/orbitalCalculations.ts"
click node_planets "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/astronomy/planetData.ts"
click node_labhome "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/lab/LabHome.tsx"
click node_labstore "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/store/labStore.ts"
click node_activities "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/content/labActivities.ts"
click node_education "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/education/EducationHub.tsx"
click node_events "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/features/astroEvents/useAstroEventScheduler.ts"
click node_eventdata "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/content/astroEvents.ts"
click node_eventlayer "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/events/AstroEventLayer.ts"
click node_hardware "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/ui/HardwarePanel.tsx"
click node_hardwarestore "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/hardware/hardwareStore.ts"
click node_voice "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/ui/VoiceHost.tsx"
click node_chatfeature "https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/features/chat/openRouter.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_explore,node_chatpanel,node_labui toneBlue
class node_canvas,node_fallback,node_scene,node_camera,node_sceneapi,node_simstore,node_eventlayer toneAmber
class node_labhome,node_labstore,node_activities,node_education,node_events,node_eventdata,node_openrouter toneMint
class node_hardware,node_hardwarestore,node_voice,node_chatfeature toneRose
class node_time,node_astro,node_planets,node_learner,node_device toneIndigo
```

## Components

### Application UI

- [App Shell](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/App.tsx): `src/App.tsx`
- [Explore Controls](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/ui/PlanetDrawer.tsx): `src/components/ui/PlanetDrawer.tsx`
- [Sun Chat Panel](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/chat/SunChatPanel.tsx): `src/components/chat/SunChatPanel.tsx`
- [Activity UI](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/lab/ActivityBody.tsx): `src/components/lab/ActivityBody.tsx`

### Simulation and Scene

- [3D Canvas Host](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/3d/CanvasHost.tsx): `src/components/3d/CanvasHost.tsx`
- [2D Fallback](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/3d/SolarSystem2D.tsx): `src/components/3d/SolarSystem2D.tsx`
- [Solar System Scene](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/SolarSystemScene.ts): `src/scene/SolarSystemScene.ts`
- [Camera Controller](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/CameraController.ts): `src/scene/CameraController.ts`
- [Scene API](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/sceneApi.ts): `src/scene/sceneApi.ts`
- [Simulation State](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/store/simulationStore.ts): `src/store/simulationStore.ts`
- [Event Visual Layer](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/scene/events/AstroEventLayer.ts): `src/scene/events/AstroEventLayer.ts`

### Learning Features

- [Lab Home](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/lab/LabHome.tsx): `src/components/lab/LabHome.tsx`
- [Lab State](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/store/labStore.ts): `src/store/labStore.ts`
- [Lab Activities](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/content/labActivities.ts): `src/content/labActivities.ts`
- [Education Panels](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/education/EducationHub.tsx): `src/components/education/EducationHub.tsx`
- [Event Scheduler](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/features/astroEvents/useAstroEventScheduler.ts): `src/features/astroEvents/useAstroEventScheduler.ts`
- [Event Content](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/content/astroEvents.ts): `src/content/astroEvents.ts`

### Optional Integrations

- [Hardware Controls](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/ui/HardwarePanel.tsx): `src/components/ui/HardwarePanel.tsx`
- [Hardware Store](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/hardware/hardwareStore.ts): `src/hardware/hardwareStore.ts`
- [Voice Host](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/components/ui/VoiceHost.tsx): `src/components/ui/VoiceHost.tsx`
- [Chat Completion](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/features/chat/openRouter.ts): `src/features/chat/openRouter.ts`

### Astronomy Domain

- [Time Engine](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/astronomy/timeEngine.ts): `src/astronomy/timeEngine.ts`
- [Astronomy Calculations](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/astronomy/orbitalCalculations.ts): `src/astronomy/orbitalCalculations.ts`
- [Planet Data](https://github.com/huseyinsihat/ufkumuzyildizlar/blob/main/src/astronomy/planetData.ts): `src/astronomy/planetData.ts`

### Other components

- **Learner**
- **Deneyap Card**
- **OpenRouter Service**

## Connections

- Learner → App Shell: uses
- App Shell → Explore Controls: renders
- App Shell → Sun Chat Panel: renders
- App Shell → Activity UI: renders
- App Shell → 3D Canvas Host: renders
- App Shell → 2D Fallback: renders
- App Shell → Lab Home: renders
- App Shell → Education Panels: renders
- App Shell → Hardware Controls: renders
- App Shell → Voice Host: renders
- App Shell → Event Scheduler: starts
- 3D Canvas Host → Solar System Scene: hosts
- Solar System Scene → Camera Controller: controls view
- Activity UI → Lab State: updates
- Activity UI → Lab Activities: reads
- Lab State → Scene API: controls scene
- Lab State → Simulation State: updates
- Lab State → Lab Activities: reads
- Solar System Scene → Astronomy Calculations: uses calculations
- Solar System Scene → Planet Data: reads data
- Event Scheduler → Event Content: schedules from
- Event Scheduler → Event Visual Layer: dispatches events
- App Shell → Hardware Store: watches ports
- Hardware Controls → Hardware Store: controls
- Hardware Store → Deneyap Card: communicates
- Sun Chat Panel → Chat Completion: requests replies
- Chat Completion → OpenRouter Service: sends chat
- Simulation State → Time Engine: uses time scale