How rohitkumarsingh0111/spacey-science works
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: App.tsx React App · server.ts Server · api.ts API client · TopicsPage.tsx Topics
Components 24
Frontend
React/Vite space-learning app
- React App · Immersive learning UI and state
frontend/src/App.tsx - Home · Landing and entry screen
frontend/src/pages/HomePage.tsx - Topics · Topic selection and discovery
frontend/src/pages/TopicsPage.tsx - Lesson · Structured lesson reading and expand-more flow
frontend/src/pages/LessonPage.tsx - Quiz · Lesson-grounded assessment screen
frontend/src/pages/QuizPage.tsx - Dashboard · Progress and rewards view
frontend/src/pages/DashboardPage.tsx - API client · Centralized backend access from the UI
frontend/src/lib/api.ts - Topic data · Local topic metadata for selection UI
frontend/src/lib/topics.ts - UI kit · Reusable buttons, cards, inputs, progress, loader
frontend/src/components/ui/button.tsx - Topic UI · Hero, stats, and 3D topic cards
frontend/src/components/topics/TopicCard3D.tsx - Space scene · Animated background and immersive scene
frontend/src/components/background/SpaceScene.tsx
Backend
Express API and AI/content services
- Server · Backend bootstrap and API wiring
backend/src/server.ts - Lesson routes · Lesson and expansion endpoints
backend/src/routes/lesson.routes.ts - Quiz routes · Quiz generation endpoints
backend/src/routes/quiz.routes.ts - Progress routes · Progress save and retrieval endpoints
backend/src/routes/progress.routes.ts - Lesson ctrl · Shapes lesson requests and responses
backend/src/controllers/lesson.controller.ts - Quiz ctrl · Shapes quiz requests and responses
backend/src/controllers/quiz.controller.ts - Progress ctrl · Handles save flow after quiz completion
backend/src/controllers/progress.controller.ts - Lesson service · Orchestrates lesson generation and expansion
backend/src/services/lesson.service.ts - AI service · Structured AI generation and validation layer
backend/src/services/ai.service.ts - Progress · Persistence for scores, badges, and completion state
backend/src/models/Progress.ts - Quiz · Persistence for quiz attempts and results
backend/src/models/Quiz.ts - User · User identity or session linkage
backend/src/models/User.ts
Other components
- Learners · People using the space-learning experience
Connections 29
- 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