# rohitkumarsingh0111/spacey-science architecture

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

- Interactive diagram: https://gitdiagram.com/rohitkumarsingh0111/spacey-science
- Repository: https://github.com/rohitkumarsingh0111/spacey-science

## Overview

1. **Overall shape**
Spacey Science is split into two deployable applications: a **React/Vite frontend** and a **Node.js/Express backend**. The frontend owns the immersive learning experience and UI state; the backend owns AI content generation, quiz generation, and persistence to MongoDB.

2. **Frontend boundary**
The frontend is a **single-page app** built with **TypeScript, React, Tailwind CSS, and Framer Motion**. Its main screens are `HomePage`, `TopicsPage`, `LessonPage`, `QuizPage`, and `DashboardPage`, which together implement the guided flow: **topic selection → lesson → quiz → progress/reward**.

3. **Frontend composition**
UI is organized into reusable layers:
- `components/background` for the space-themed animated scene
- `components/topics` for topic cards, hero content, and stats
- `components/ui` for low-level controls like buttons, cards, inputs, and progress
- `components/Loader.tsx` for asynchronous states  
This indicates a design system-like structure rather than page-specific styling.

4. **Frontend data access**
`src/lib/api.ts` is the frontend’s server boundary. It centralizes calls to the backend API so pages and components do not talk to endpoints directly. `src/lib/topics.ts` likely provides local topic metadata used to seed the topic-selection UI, while `src/types` defines shared shapes for lesson, quiz, and progress data.

5. **Learning flow**
The main product flow is intentionally linear and stateful:
- user selects a space topic
- frontend requests a generated lesson
- lesson renders as structured sections
- a “Learn More” action expands a selected section
- frontend requests a quiz grounded in that lesson
- score/progress is saved after quiz completion  
This is the core business workflow the architecture should center on.

6. **Backend boundary**
The backend is a **REST API** built with **Express** and organized in a classic **controller → service → model** layout. `server.ts` is the entry point, `routes/*.routes.ts` define endpoints, `controllers/*.controller.ts` handle request/response shaping, `services/*.service.ts` contain AI/business logic, and `models/*.ts` define MongoDB entities.

7. **AI subsystem**
The most important backend subsystem is the AI generation layer in `services/ai.service.ts` and `services/lesson.service.ts`. This layer generates:
- structured lesson content
- expanded explanations for a selected section
- quiz questions grounded in lesson context  
The README emphasizes strict JSON/schema handling and fallback behavior, so the AI layer is not a freeform chatbot; it is a controlled content-generation service.

8. **Persistence subsystem**
MongoDB is used for **progress and achievement persistence**. The `User`, `Quiz`, and `Progress` models suggest storage for user identity or session linkage, quiz attempts/scores, and badge or completion state. `progress.controller.ts` and `progress.routes.ts` expose the save path used after quiz completion.

9. **API surface**
The backend API is small and focused:
- lesson generation and expansion
- quiz generation
- progress save
- health check  
This makes the backend a narrow orchestration layer between the UI, the AI provider, and the database rather than a broad domain API.

10. **Important architectural characteristics**
The repo is designed around **defensive AI integration**: structured outputs, validation, and safe rendering on the frontend. The frontend is optimized for cognitive clarity and motion-guided UX, while the backend is optimized for predictable machine-generated content and persistence. That separation is the key architectural boundary.

11. **Runtime and deployment shape**
The project is production-oriented with separate frontend and backend deployments, which means the architecture is effectively **client app + API service + database**. The frontend can be hosted independently, while the backend exposes the REST endpoints consumed by the app.

12. **What to draw in a diagram**
A good architecture diagram should show:
- users interacting with the React frontend
- frontend pages/components calling `lib/api.ts`
- REST calls into Express routes/controllers
- controllers delegating to AI/content services
- services reading/writing MongoDB models
- persisted progress feeding back into the Dashboard/quiz completion flow  
The most important arrows are the ones carrying **lesson content, quiz payloads, and progress state**.

Main entry points: [`frontend/src/App.tsx`](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/App.tsx) (React App), [`backend/src/server.ts`](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/server.ts) (Server), [`frontend/src/lib/api.ts`](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/lib/api.ts) (API client), [`frontend/src/pages/TopicsPage.tsx`](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/TopicsPage.tsx) (Topics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["React App<br/>spa<br/>[App.tsx]"]
  node_home_page["Home<br/>page<br/>[HomePage.tsx]"]
  node_topics_page["Topics<br/>page<br/>[TopicsPage.tsx]"]
  node_lesson_page["Lesson<br/>page<br/>[LessonPage.tsx]"]
  node_quiz_page["Quiz<br/>page<br/>[QuizPage.tsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[DashboardPage.tsx]"]
  node_frontend_api["API client<br/>http client<br/>[api.ts]"]
  node_topic_data["Topic data<br/>content data<br/>[topics.ts]"]
  node_ui_shell["UI kit<br/>components<br/>[button.tsx]"]
  node_topic_ui["Topic UI<br/>components<br/>[TopicCard3D.tsx]"]
  node_space_scene["Space scene<br/>visual layer<br/>[SpaceScene.tsx]"]
end

subgraph group_backend["Backend"]
  node_server_entry["Server<br/>express entry<br/>[server.ts]"]
  node_lesson_routes["Lesson routes<br/>[lesson.routes.ts]"]
  node_quiz_routes["Quiz routes<br/>[quiz.routes.ts]"]
  node_progress_routes["Progress routes<br/>[progress.routes.ts]"]
  node_lesson_controller["Lesson ctrl<br/>controller"]
  node_quiz_controller["Quiz ctrl<br/>controller<br/>[quiz.controller.ts]"]
  node_progress_controller["Progress ctrl<br/>controller"]
  node_lesson_service["Lesson service<br/>[lesson.service.ts]"]
  node_ai_service["AI service<br/>[ai.service.ts]"]
  node_progress_model[("Progress<br/>mongo model<br/>[Progress.ts]")]
  node_quiz_model[("Quiz<br/>mongo model<br/>[Quiz.ts]")]
  node_user_model[("User<br/>mongo model<br/>[User.ts]")]
end

node_users(("Learners<br/>actor"))

node_users -->|"learns"| node_frontend_app
node_frontend_app -->|"routes to"| node_home_page
node_frontend_app -->|"routes to"| node_topics_page
node_frontend_app -->|"routes to"| node_lesson_page
node_frontend_app -->|"routes to"| node_quiz_page
node_frontend_app -->|"routes to"| node_dashboard_page
node_topics_page -->|"reads"| node_topic_data
node_home_page -->|"uses"| node_space_scene
node_topics_page -->|"uses"| node_topic_ui
node_lesson_page -->|"uses"| node_ui_shell
node_quiz_page -->|"uses"| node_ui_shell
node_dashboard_page -->|"uses"| node_ui_shell
node_lesson_page -->|"requests lesson"| node_frontend_api
node_quiz_page -->|"requests quiz"| node_frontend_api
node_dashboard_page -->|"saves progress"| node_frontend_api
node_frontend_api -->|"REST calls"| node_server_entry
node_server_entry -->|"mounts"| node_lesson_routes
node_server_entry -->|"mounts"| node_quiz_routes
node_server_entry -->|"mounts"| node_progress_routes
node_lesson_routes -->|"delegates"| node_lesson_controller
node_quiz_routes -->|"delegates"| node_quiz_controller
node_progress_routes -->|"delegates"| node_progress_controller
node_lesson_controller -->|"orchestrates"| node_lesson_service
node_quiz_controller -->|"generates"| node_ai_service
node_lesson_service -->|"generates"| node_ai_service
node_progress_controller -->|"writes"| node_progress_model
node_quiz_controller -->|"writes"| node_quiz_model
node_progress_controller -->|"links"| node_user_model
node_ai_service -.->|"reads schema"| node_quiz_model

click node_frontend_app "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/App.tsx"
click node_home_page "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/HomePage.tsx"
click node_topics_page "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/TopicsPage.tsx"
click node_lesson_page "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/LessonPage.tsx"
click node_quiz_page "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/QuizPage.tsx"
click node_dashboard_page "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/DashboardPage.tsx"
click node_frontend_api "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/lib/api.ts"
click node_topic_data "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/lib/topics.ts"
click node_ui_shell "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/components/ui/button.tsx"
click node_topic_ui "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/components/topics/TopicCard3D.tsx"
click node_space_scene "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/components/background/SpaceScene.tsx"
click node_server_entry "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/server.ts"
click node_lesson_routes "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/routes/lesson.routes.ts"
click node_quiz_routes "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/routes/quiz.routes.ts"
click node_progress_routes "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/routes/progress.routes.ts"
click node_lesson_controller "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/controllers/lesson.controller.ts"
click node_quiz_controller "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/controllers/quiz.controller.ts"
click node_progress_controller "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/controllers/progress.controller.ts"
click node_lesson_service "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/services/lesson.service.ts"
click node_ai_service "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/services/ai.service.ts"
click node_progress_model "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/models/Progress.ts"
click node_quiz_model "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/models/Quiz.ts"
click node_user_model "https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/models/User.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_frontend_app,node_home_page,node_topics_page,node_lesson_page,node_quiz_page,node_dashboard_page,node_frontend_api,node_topic_data,node_ui_shell,node_topic_ui,node_space_scene toneBlue
class node_server_entry,node_lesson_routes,node_quiz_routes,node_progress_routes,node_lesson_controller,node_quiz_controller,node_progress_controller,node_lesson_service,node_ai_service,node_progress_model,node_quiz_model,node_user_model toneAmber
class node_users toneNeutral
```

## Components

### Frontend

React/Vite space-learning app

- [React App](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/App.tsx): spa · Immersive learning UI and state · `frontend/src/App.tsx`
- [Home](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/HomePage.tsx): page · Landing and entry screen · `frontend/src/pages/HomePage.tsx`
- [Topics](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/TopicsPage.tsx): page · Topic selection and discovery · `frontend/src/pages/TopicsPage.tsx`
- [Lesson](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/LessonPage.tsx): page · Structured lesson reading and expand-more flow · `frontend/src/pages/LessonPage.tsx`
- [Quiz](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/QuizPage.tsx): page · Lesson-grounded assessment screen · `frontend/src/pages/QuizPage.tsx`
- [Dashboard](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/pages/DashboardPage.tsx): page · Progress and rewards view · `frontend/src/pages/DashboardPage.tsx`
- [API client](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/lib/api.ts): http client · Centralized backend access from the UI · `frontend/src/lib/api.ts`
- [Topic data](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/lib/topics.ts): content data · Local topic metadata for selection UI · `frontend/src/lib/topics.ts`
- [UI kit](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/components/ui/button.tsx): components · Reusable buttons, cards, inputs, progress, loader · `frontend/src/components/ui/button.tsx`
- [Topic UI](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/components/topics/TopicCard3D.tsx): components · Hero, stats, and 3D topic cards · `frontend/src/components/topics/TopicCard3D.tsx`
- [Space scene](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/frontend/src/components/background/SpaceScene.tsx): visual layer · Animated background and immersive scene · `frontend/src/components/background/SpaceScene.tsx`

### Backend

Express API and AI/content services

- [Server](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/server.ts): express entry · Backend bootstrap and API wiring · `backend/src/server.ts`
- [Lesson routes](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/routes/lesson.routes.ts): routes · Lesson and expansion endpoints · `backend/src/routes/lesson.routes.ts`
- [Quiz routes](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/routes/quiz.routes.ts): routes · Quiz generation endpoints · `backend/src/routes/quiz.routes.ts`
- [Progress routes](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/routes/progress.routes.ts): routes · Progress save and retrieval endpoints · `backend/src/routes/progress.routes.ts`
- [Lesson ctrl](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/controllers/lesson.controller.ts): controller · Shapes lesson requests and responses · `backend/src/controllers/lesson.controller.ts`
- [Quiz ctrl](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/controllers/quiz.controller.ts): controller · Shapes quiz requests and responses · `backend/src/controllers/quiz.controller.ts`
- [Progress ctrl](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/controllers/progress.controller.ts): controller · Handles save flow after quiz completion · `backend/src/controllers/progress.controller.ts`
- [Lesson service](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/services/lesson.service.ts): service · Orchestrates lesson generation and expansion · `backend/src/services/lesson.service.ts`
- [AI service](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/services/ai.service.ts): service · Structured AI generation and validation layer · `backend/src/services/ai.service.ts`
- [Progress](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/models/Progress.ts): mongo model · Persistence for scores, badges, and completion state · `backend/src/models/Progress.ts`
- [Quiz](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/models/Quiz.ts): mongo model · Persistence for quiz attempts and results · `backend/src/models/Quiz.ts`
- [User](https://github.com/rohitkumarsingh0111/spacey-science/blob/main/backend/src/models/User.ts): mongo model · User identity or session linkage · `backend/src/models/User.ts`

### Other components

- **Learners**: actor · People using the space-learning experience

## Connections

- Learners → React App: learns · Learners use the app experience
- React App → Home: routes to · App renders the guided flow screens
- React App → Topics: routes to · App renders the guided flow screens
- React App → Lesson: routes to · App renders the guided flow screens
- React App → Quiz: routes to · App renders the guided flow screens
- React App → Dashboard: routes to · App renders the guided flow screens
- Topics → Topic data: reads · Topic selection is seeded by local metadata
- Home → Space scene: uses · Landing view uses the animated space backdrop
- Topics → Topic UI: uses · Topic discovery uses specialized UI composition
- Lesson → UI kit: uses · Lesson rendering relies on shared UI controls
- Quiz → UI kit: uses · Quiz interaction relies on shared UI controls
- Dashboard → UI kit: uses · Progress view relies on shared UI controls
- Lesson → API client: requests lesson · Fetches generated lessons and expansions
- Quiz → API client: requests quiz · Fetches quiz payloads grounded in lesson context
- Dashboard → API client: saves progress · Sends completion and score data
- API client → Server: REST calls · Frontend talks only through the API boundary
- Server → Lesson routes: mounts · Server registers lesson endpoints
- Server → Quiz routes: mounts · Server registers quiz endpoints
- Server → Progress routes: mounts · Server registers progress endpoints
- Lesson routes → Lesson ctrl: delegates · Routes pass lesson requests to controllers
- Quiz routes → Quiz ctrl: delegates · Routes pass quiz requests to controllers
- Progress routes → Progress ctrl: delegates · Routes pass progress requests to controllers
- Lesson ctrl → Lesson service: orchestrates · Controller coordinates lesson workflow
- Quiz ctrl → AI service: generates · Controller requests quiz content from AI layer
- Lesson service → AI service: generates · Lesson workflow uses controlled AI generation
- Progress ctrl → Progress: writes · Completion and reward state is persisted
- Quiz ctrl → Quiz: writes · Quiz attempts and outcomes are stored
- Progress ctrl → User: links · Progress can be associated with a user
- AI service → Quiz: reads schema · Quiz generation uses stored lesson/quiz structure
