# yeinchingg/galaxy architecture

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

- Interactive diagram: https://gitdiagram.com/yeinchingg/galaxy
- Repository: https://github.com/yeinchingg/galaxy

## Overview

StarLearn is an astronomy-physics learning platform. The user journey spans account access, interactive astronomy content, AI-assisted learning, and recorded learning activity. Its backend serves frontend pages and APIs; RAG chat coordinates retrieval, conversation history, and generated answers, while a separate physics model supports stellar-evolution calculations. The README documents NASA daily content, 3D narration, and personalized recommendations, but sampled source does not establish all of their runtime wiring; those links are omitted or marked unverified.

Main entry points: [`app/adapters/controllers/chat_controller.py`](https://github.com/yeinchingg/galaxy/blob/main/app/adapters/controllers/chat_controller.py) (Chat and activity API), [`main.py`](https://github.com/yeinchingg/galaxy/blob/main/main.py) (FastAPI application), [`app/use_cases/rag_chat_use_case.py`](https://github.com/yeinchingg/galaxy/blob/main/app/use_cases/rag_chat_use_case.py) (RAG chat orchestration), [`app/infrastructure/database/database.py`](https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/database/database.py) (User and chat data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Learning interface"]
  node_frontend["Web pages<br/>[index.html]"]
  node_auth_ui["Account UI<br/>[auth.js]"]
  node_sky["3D sky engine<br/>[sky_engine.js]"]
  node_hr["H-R exploration<br/>[hr.html]"]
  node_news_ui["News and tracking<br/>[fetch_news.js]"]
  node_wiki["Astronomy wiki<br/>[wiki_data.js]"]
end

subgraph group_api["API and adapters"]
  node_server["FastAPI application<br/>[main.py]"]
  node_chat_api["Chat and activity API<br/>[chat_controller.py]"]
  node_auth_api["Authentication API<br/>[auth_controller.py]"]
end

subgraph group_learning["Learning services"]
  node_rag["RAG chat orchestration"]
  node_star_case["Star simulation"]
  node_physics["Stellar physics<br/>[star_physics.py]"]
  node_interfaces["Service contracts<br/>[interfaces.py]"]
end

subgraph group_infra["Infrastructure"]
  node_database[("User and chat data<br/>[database.py]")]
  node_gemini["Gemini AI<br/>[gemini_service.py]"]
  node_pinecone[("Pinecone search")]
  node_news_service["Astronomy news client<br/>[news_client.py]"]
end

node_learner(("Learner"))
node_ai_provider["Google Gemini"]
node_vector_provider[("Pinecone")]
node_news_provider["News data service"]

node_learner -->|"uses"| node_frontend
node_frontend -->|"requests pages"| node_server
node_auth_ui -.->|"authenticates"| node_auth_api
node_frontend -->|"calls APIs"| node_chat_api
node_chat_api -->|"invokes chat"| node_rag
node_chat_api -->|"reads and writes"| node_database
node_auth_api -->|"reads and writes"| node_database
node_rag -->|"generates answers"| node_gemini
node_rag -->|"searches context"| node_pinecone
node_rag -->|"loads history"| node_database
node_server -->|"configures"| node_rag
node_server -->|"creates service"| node_gemini
node_server -->|"creates service"| node_pinecone
node_server -->|"creates repository"| node_database
node_gemini -->|"calls API"| node_ai_provider
node_pinecone -->|"queries index"| node_vector_provider
node_chat_api -->|"fetches articles"| node_news_provider
node_news_ui -.->|"requests news"| node_chat_api
node_learner -->|"explores objects"| node_sky
node_learner -->|"explores evolution"| node_hr
node_star_case -->|"calculates evolution"| node_physics
node_sky -.->|"requests narration"| node_chat_api
node_news_service -.->|"retrieves content"| node_news_provider
node_wiki -.->|"presents references"| node_learner

click node_frontend "https://github.com/yeinchingg/galaxy/blob/main/frontend/index.html"
click node_auth_ui "https://github.com/yeinchingg/galaxy/blob/main/frontend/auth.js"
click node_sky "https://github.com/yeinchingg/galaxy/blob/main/frontend/sky_engine.js"
click node_hr "https://github.com/yeinchingg/galaxy/blob/main/frontend/hr.html"
click node_news_ui "https://github.com/yeinchingg/galaxy/blob/main/frontend/fetch_news.js"
click node_wiki "https://github.com/yeinchingg/galaxy/blob/main/frontend/wiki_data.js"
click node_server "https://github.com/yeinchingg/galaxy/blob/main/main.py"
click node_chat_api "https://github.com/yeinchingg/galaxy/blob/main/app/adapters/controllers/chat_controller.py"
click node_auth_api "https://github.com/yeinchingg/galaxy/blob/main/app/adapters/controllers/auth_controller.py"
click node_rag "https://github.com/yeinchingg/galaxy/blob/main/app/use_cases/rag_chat_use_case.py"
click node_star_case "https://github.com/yeinchingg/galaxy/blob/main/app/use_cases/star_simulation_use_case.py"
click node_physics "https://github.com/yeinchingg/galaxy/blob/main/app/domain/star_physics.py"
click node_interfaces "https://github.com/yeinchingg/galaxy/blob/main/app/domain/interfaces.py"
click node_database "https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/database/database.py"
click node_gemini "https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/external_ai/gemini_service.py"
click node_pinecone "https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/external_ai/pinecone_service.py"
click node_news_service "https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/news_client.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_frontend,node_auth_ui,node_sky,node_hr,node_news_ui,node_wiki toneBlue
class node_server,node_chat_api,node_auth_api,node_vector_provider toneAmber
class node_rag,node_star_case,node_physics,node_interfaces toneMint
class node_database,node_gemini,node_pinecone,node_news_service toneRose
class node_learner,node_ai_provider,node_news_provider toneIndigo
```

## Components

### Learning interface

- [Web pages](https://github.com/yeinchingg/galaxy/blob/main/frontend/index.html): `frontend/index.html`
- [Account UI](https://github.com/yeinchingg/galaxy/blob/main/frontend/auth.js): `frontend/auth.js`
- [3D sky engine](https://github.com/yeinchingg/galaxy/blob/main/frontend/sky_engine.js): `frontend/sky_engine.js`
- [H-R exploration](https://github.com/yeinchingg/galaxy/blob/main/frontend/hr.html): `frontend/hr.html`
- [News and tracking](https://github.com/yeinchingg/galaxy/blob/main/frontend/fetch_news.js): `frontend/fetch_news.js`
- [Astronomy wiki](https://github.com/yeinchingg/galaxy/blob/main/frontend/wiki_data.js): `frontend/wiki_data.js`

### API and adapters

- [FastAPI application](https://github.com/yeinchingg/galaxy/blob/main/main.py): `main.py`
- [Chat and activity API](https://github.com/yeinchingg/galaxy/blob/main/app/adapters/controllers/chat_controller.py): `app/adapters/controllers/chat_controller.py`
- [Authentication API](https://github.com/yeinchingg/galaxy/blob/main/app/adapters/controllers/auth_controller.py): `app/adapters/controllers/auth_controller.py`

### Learning services

- [RAG chat orchestration](https://github.com/yeinchingg/galaxy/blob/main/app/use_cases/rag_chat_use_case.py): `app/use_cases/rag_chat_use_case.py`
- [Star simulation](https://github.com/yeinchingg/galaxy/blob/main/app/use_cases/star_simulation_use_case.py): `app/use_cases/star_simulation_use_case.py`
- [Stellar physics](https://github.com/yeinchingg/galaxy/blob/main/app/domain/star_physics.py): `app/domain/star_physics.py`
- [Service contracts](https://github.com/yeinchingg/galaxy/blob/main/app/domain/interfaces.py): `app/domain/interfaces.py`

### Infrastructure

- [User and chat data](https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/database/database.py): `app/infrastructure/database/database.py`
- [Gemini AI](https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/external_ai/gemini_service.py): `app/infrastructure/external_ai/gemini_service.py`
- [Pinecone search](https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/external_ai/pinecone_service.py): `app/infrastructure/external_ai/pinecone_service.py`
- [Astronomy news client](https://github.com/yeinchingg/galaxy/blob/main/app/infrastructure/news_client.py): `app/infrastructure/news_client.py`

### Other components

- **Learner**
- **Google Gemini**
- **Pinecone**
- **News data service**

## Connections

- Learner → Web pages: uses (evidence: `README.md`)
- Web pages → FastAPI application: requests pages (evidence: `main.py`)
- Account UI → Authentication API: authenticates
- Web pages → Chat and activity API: calls APIs (evidence: `README.md`)
- Chat and activity API → RAG chat orchestration: invokes chat (evidence: `app/adapters/controllers/chat_controller.py`)
- Chat and activity API → User and chat data: reads and writes (evidence: `app/adapters/controllers/chat_controller.py`)
- Authentication API → User and chat data: reads and writes (evidence: `app/adapters/controllers/auth_controller.py`)
- RAG chat orchestration → Gemini AI: generates answers (evidence: `app/use_cases/rag_chat_use_case.py`)
- RAG chat orchestration → Pinecone search: searches context (evidence: `app/use_cases/rag_chat_use_case.py`)
- RAG chat orchestration → User and chat data: loads history (evidence: `app/use_cases/rag_chat_use_case.py`)
- FastAPI application → RAG chat orchestration: configures (evidence: `main.py`)
- FastAPI application → Gemini AI: creates service (evidence: `main.py`)
- FastAPI application → Pinecone search: creates service (evidence: `main.py`)
- FastAPI application → User and chat data: creates repository (evidence: `main.py`)
- Gemini AI → Google Gemini: calls API (evidence: `app/infrastructure/external_ai/gemini_service.py`)
- Pinecone search → Pinecone: queries index (evidence: `app/infrastructure/external_ai/pinecone_service.py`)
- Chat and activity API → News data service: fetches articles (evidence: `app/adapters/controllers/chat_controller.py`)
- News and tracking → Chat and activity API: requests news
- Learner → 3D sky engine: explores objects (evidence: `README.md`)
- Learner → H-R exploration: explores evolution (evidence: `README.md`)
- Star simulation → Stellar physics: calculates evolution (evidence: `app/use_cases/star_simulation_use_case.py`)
- 3D sky engine → Chat and activity API: requests narration
- Astronomy news client → News data service: retrieves content
- Astronomy wiki → Learner: presents references
