Temirqazyq - AI-Powered Learning Platform

A complete full-stack web application that generates personalized learning roadmaps using AI. Users can learn any topic through structured lessons, quizzes, and progress tracking.

🚀 Features

• AI-Generated Roadmaps: Generate end-to-end learning paths (beginner → senior) with prerequisites, XP rewards, and quizzes.
• Guided Graph UI: Roadmaps render as a Duolingo-style path using react-force-graph-2d with locked progression, tooltips, and click-to-learn interactions.
• Verified Materials: Each node includes real-world YouTube videos, official documentation, and trusted articles (no fabricated links).
• Universal Navigation: Consistent navigation across all pages (Home, Dashboard, Explain, Roadmaps) with responsive design and language selection.
• 3-Level Explanations: “Explain like I’m 5 / student / specialist” output for any topic.
• Interactive Lessons: Materials, quizzes, and a “complete lesson” flow that awards XP/streaks/achievements.
• Profile Dashboard: New profile-first dashboard with avatar hover state, XP bar, streak/XP/achievements cards, completed-lesson showcase, settings modal (updates email/username/password via backend), and logout confirmation dialog.
• Progress Tracking: XP, streaks, achievements, recent progress feed, and completed-node tracking for graph locking.
• Roadmaps List with Progress: Dedicated /roadmaps page that lists every roadmap and shows green progress bars based on completed lessons.
• AI Quiz Feedback: Automatic grading plus AI-generated encouragement and review tips.

🛠️ Tech Stack

Backend

• FastAPI - Modern Python web framework
• PostgreSQL - Relational database
• SQLAlchemy - ORM for database operations
• JWT - Authentication
• Google Gemini API - Free AI-powered content generation

Frontend

• Next.js 14 - React framework with App Router
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• Zustand - State management
• shadcn/ui - UI component library
• flag-icons - High-resolution, accurate SVG country flags for cross-platform support

📋 Prerequisites

• Python 3.10+ (Python 3.11+ recommended for better package compatibility)
• Node.js 18+
• PostgreSQL 12+
• Google Gemini API key (free from https://makersuite.google.com/app/apikey)
• Rust & Cargo (required for Python 3.14+ or if packages need to be compiled from source)

🔧 Setup Instructions

Backend Setup

1. Navigate to backend directory:

   cd backend

2. Create a virtual environment:

   python -m venv venv

3. Activate virtual environment:

   • Windows:

     venv\Scripts\activate

   • Linux/Mac:

     source venv/bin/activate

4. Install Rust (if needed):

   Some Python packages (like pydantic-core) may require Rust to compile from source. This is especially needed if using Python 3.14+.

   Install Rust:

   • Visit https://rustup.rs/
   • Download and run the installer
   • Or use: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh (Linux/Mac)

   Add Rust to PATH (Windows):

   1. Open System Properties → Environment Variables
   2. Edit the "Path" variable under User variables
   3. Add: %USERPROFILE%\.cargo\bin
   4. Restart your terminal/PowerShell

   Verify installation:

   cargo --version
   rustc --version

   Note: If you encounter build errors during pip install, ensure Rust is properly installed and added to PATH.

5. Install dependencies:

   pip install -r requirements.txt

6. Set up environment variables: Create a .env file in the backend directory:

   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/temirqazyq
   SECRET_KEY=your-secret-key-here-change-in-production
   GEMINI_API_KEY=your-gemini-api-key-here
   GEMINI_MODEL=gemini-flash-latest
   CORS_ORIGINS=["http://localhost:3000"]

   To get a free Gemini API key:

   1. Go to https://makersuite.google.com/app/apikey
   2. Sign in with your Google account
   3. Click "Create API Key"
   4. Copy the key and paste it in your .env file

7. Create PostgreSQL database:

   CREATE DATABASE temirqazyq;

8. Run the backend:

   uvicorn app.main:app --reload --port 8000

   The API will be available at http://localhost:8000 API documentation at http://localhost:8000/docs

Frontend Setup

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   npm install

3. Set up environment variables (optional): Create a .env.local file in the frontend directory:

   NEXT_PUBLIC_API_URL=http://localhost:8000

4. Run the development server:

   npm run dev

   The frontend will be available at http://localhost:3000

📁 Project Structure

Temirqazyq/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   │   └── v1/
│   │   │       └── routes/
│   │   │           ├── auth.py
│   │   │           ├── roadmap.py
│   │   │           ├── explain.py
│   │   │           ├── progress.py
│   │   │           └── quiz.py
│   │   ├── core/
│   │   │   ├── config.py
│   │   │   ├── database.py
│   │   │   └── security.py
│   │   ├── models/
│   │   │   ├── user.py
│   │   │   ├── roadmap.py
│   │   │   ├── lesson.py
│   │   │   └── progress.py
│   │   ├── schemas/
│   │   │   ├── auth.py
│   │   │   ├── roadmap.py
│   │   │   ├── explain.py
│   │   │   ├── quiz.py
│   │   │   └── progress.py
│   │   ├── services/
│   │   │   ├── roadmap_generator.py
│   │   │   ├── explanation_generator.py
│   │   │   ├── level_evaluator.py
│   │   │   └── material_fetcher.py
│   │   ├── utils/
│   │   │   └── openai_client.py
│   │   └── main.py
│   └── requirements.txt
│
└── frontend/
    ├── app/
    │   ├── page.tsx
    │   ├── dashboard/
    │   ├── roadmap/
    │   ├── lesson/
    │   ├── explain/
    │   └── auth/
    ├── components/
    │   ├── ui/
    │   ├── roadmap/
    │   │   ├── roadmap-graph.tsx
    │   │   └── roadmap-page.tsx
    │   ├── roadmap-tree.tsx
    │   ├── quiz-card.tsx
    │   └── xp-bar.tsx
    ├── lib/
    │   ├── api.ts
    │   └── auth.ts
    ├── store/
    │   ├── user.ts
    │   └── progress.ts
    └── package.json

📚 Feature Reference

For a deep dive into every capability, architecture decisions, and the external resources leveraged, see FEATURES.md.

🎯 Usage

1. Register/Login – create an account or sign in.
2. Generate a Roadmap – enter a topic and (optionally) choose the Max nodes slider to control roadmap size.
3. Explore the Graph – the guided ForceGraph displays every node; pan/zoom to inspect later lessons and hover for tooltips.
4. Open a Lesson – click an unlocked node to jump to /learn/[node-id], review materials, and take quizzes.
5. Complete Lessons – mark lessons done to gain XP/streaks; newly unlocked nodes turn blue/green in the graph.
6. Track Progress – dashboard shows XP, streak, achievements, recent actions, and completed nodes.
7. Ask for Explanations – use the Explain page for child/student/specialist summaries of any topic.

🔐 API Endpoints

Authentication

• POST /auth/register - Register new user
• POST /auth/login - Login and get token

Roadmaps

• POST /roadmap/generate - Generate new roadmap (body supports {"topic": "React", "max_nodes": 12})
• GET /roadmap/ - Get all user roadmaps
• GET /roadmap/{id} - Get specific roadmap

Explanations

• POST /explain/ - Get 3-level explanations

Progress

• GET /progress/stats - Get user statistics
• GET /progress/completed-nodes - Return IDs of completed lessons (used to lock/unlock roadmap nodes)
• POST /progress/complete-lesson/{node_id} - Complete a lesson

Quiz

• POST /quiz/evaluate - Evaluate quiz answers

🧪 Testing

Backend

cd backend
pytest  # If you add tests

Frontend

cd frontend
npm run lint

🚨 Important Notes

1. Gemini API Key: Get a free API key from https://makersuite.google.com/app/apikey and set it in the backend .env file
2. Database: Ensure PostgreSQL is running and the database is created
3. CORS: Update CORS origins in backend/app/core/config.py for production
4. Security: Change the SECRET_KEY in production
5. Environment Variables: Never commit .env files to version control

🐛 Troubleshooting

Backend Issues

• Database connection error: Check PostgreSQL is running and DATABASE_URL is correct
• Gemini API error: Verify API key is set correctly (get free key from https://makersuite.google.com/app/apikey)
• Import errors: Ensure virtual environment is activated
• Rust/Cargo build errors:
  • If you see errors about missing cargo or rustc when installing packages:
    1. Install Rust from https://rustup.rs/
    2. Add Rust to PATH: %USERPROFILE%\.cargo\bin (Windows) or ~/.cargo/bin (Linux/Mac)
    3. Restart your terminal and try again
  • For Python 3.14+: Some packages may not have pre-built wheels yet. Consider using Python 3.11 or 3.13 for better compatibility

Frontend Issues

• API connection error: Check backend is running on port 8000
• Build errors: Delete node_modules and .next, then reinstall
• CORS errors: Verify CORS_ORIGINS includes frontend URL
• npm audit glob advisory: npm audit currently reports a high-severity issue in glob pulled in by eslint-config-next@14.2.5. This dependency is used only for local linting (devDependencies). Because upgrading to a patched version requires jumping to the Next 15 / ESLint 9 toolchain, the project intentionally stays on the 14.x stack for compatibility. It’s safe to ignore this warning during local development; do not run npm audit fix --force unless you plan to upgrade the entire linting toolchain.

📝 License

This project is open source and available under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues and questions, please open an issue on the repository.

---

Built with ❤️ using FastAPI, Next.js, and OpenAI