Academic Odyssey

Academic Odyssey is a scene-first edtech prototype that reframes study as a guided scholarly expedition.
It combines quest-based learning flows, LLM-assisted study support, and a heritage-cyber visual system built around academic spaces rather than dashboard cards.

---

Overview

This project is built around three ideas:

• quest-based learning instead of flat task management
• AI-guided planning, hinting, and review
• scene-led product design for an immersive academic experience

The current prototype includes:

• identity entry and journey gateway flows
• a Great Hall dashboard
• archive and research library routes
• an AI planning chamber
• a constellation-based growth route
• a complete quest arc:
  • quest details
  • study method selection
  • deep study
  • trial
  • completion

---

Core Flow

Academic Odyssey turns study into a guided loop:

goal → plan → quest → focused study → trial / review → progress feedback

The intended user flow is:

1. define a study goal and current context
2. receive an AI-generated learning plan
3. enter the next quest step
4. complete focused study or trial-based practice
5. receive progress feedback and the next recommendation

Scholar Login

Welcome Map

Great Hall Dashboard

AI Planning Chamber

Quest Arc

Constellation Growth Route

Achievement Celebration

---

Tech Stack

• React 19
• TypeScript
• Vite
• React Router
• Zustand
• Express
• Tailwind CSS v4
• Lucide icons
• Three.js / React Three Fiber

---

Current Status

What is already in place:

• scene-first UI architecture
• route-group based shell and backdrop system
• centralized route, navigation, and quest content config
• AI provider abstraction
• MiniMax-first provider configuration

What still needs work:

• interface polish and consistency
• motion and transition refinement
• stronger visual alignment with the target experience

---

AI Provider Configuration

The current backend supports provider-based AI integration through server-side endpoints:

• POST /api/ai/plan
• POST /api/ai/hint
• POST /api/ai/review

Supported provider values:

• minimax
• gemini

Environment variables:

• AI_PROVIDER
• GEMINI_API_KEY
• MINIMAX_API_KEY
• MINIMAX_BASE_URL
• AI_MODEL_PLAN
• AI_MODEL_HINT
• AI_MODEL_REVIEW

Notes:

• provider secrets stay server-side only
• MiniMax is the default provider in the current setup
• different API key formats may behave differently depending on provider account setup

[ADD IMAGE: AI planning loop diagram here]
Suggested file: ./docs/screenshots/ai-planning-loop.png

---

Project Structure

server/                     AI provider and server-side integration
src/
  components/
    artwork/                visual anchor components
    layout/                 shell, backdrop, lighting, nav
    primitives/             low-level reusable scene UI
    stages/                 page master stage containers
  config/                   routes, navigation, scene metadata
  data/                     quest and content definitions
  lib/                      client engines and shared helpers
  pages/                    route-level page shells
  styles/                   scene system styles