Skip to content

FEATURES.md

Latest commit

 

History

History
251 lines (184 loc) · 8.88 KB

FEATURES.md

File metadata and controls

251 lines (184 loc) · 8.88 KB

Temirqazyq Feature Glossary

This document describes every major feature in the Temirqazyq platform, the internal files/endpoints involved, and external libraries/APIs used.

Table of Contents

  1. AI Roadmap Generation
  2. Guided Roadmap Graph UI
  3. Lesson Experience
  4. Learning Materials (Verified Resources)
  5. Explain Like Child/Student/Specialist
  6. Quizzes & AI Feedback
  7. Progress, XP, Streaks, Achievements
  8. Profile Dashboard & Settings
  9. Roadmaps Listing & Progress
  10. Authentication & JWT
  11. Multi-language Support
  12. Universal Navigation
  13. Tech Stack & External Dependencies

Universal Navigation

Files

  • frontend/components/navbar.tsx
  • All page files in frontend/app/

Behavior

  • A shared Navbar component ensures consistent look and feel across the platform.
  • Includes quick links to Home, Dashboard, Explain Anything, and Roadmaps.
  • Adapts visibility of "Settings" and "Logout" buttons based on the page (primarily shown on Dashboard).
  • Integrated LanguageSelector for seamless translation switching.
  • Responsive design: hides secondary actions on smaller screens to maintain usability.

AI Roadmap Generation

Files / Modules

  • backend/app/services/roadmap_generator.py
  • backend/app/api/v1/routes/roadmap.py
  • backend/app/schemas/roadmap.py

Behavior

  • Accepts topic and optional max_nodes (for testing or compact roadmaps).
  • Uses Google Gemini via call_openai() to produce hierarchical JSON with nodes, prerequisites, quizzes, and descriptions.
  • Recursively fetches learning materials per node.
  • Prunes the resulting tree if max_nodes is supplied.

External Dependencies

  • Gemini API via google-generativeai.

Guided Roadmap Graph UI

Files

  • frontend/components/roadmap/roadmap-graph.tsx
  • frontend/components/roadmap/roadmap-page.tsx
  • frontend/app/roadmap/[id]/page.tsx

Behavior

  • Rendered with react-force-graph-2d.
  • Node status colors: green (completed), blue (current), gray (locked).
  • Hover tooltips display node titles; click navigates to /learn/[node-id].
  • Graph is laid out top-to-bottom with deterministic positions and locked progression.
  • Auto-fit on load and allows pan/zoom (node dragging disabled).

Route Flow

  1. /roadmap/[id] uses RoadmapPage.
  2. Fetches roadmap data + completed node IDs.
  3. Renders both graph and summary metrics (total nodes, completed, locked).

External Dependencies

  • react-force-graph-2d

Lesson Experience

Files

  • frontend/app/lesson/[id]/page.tsx
  • (alias) frontend/app/learn/[id]/page.tsx
  • frontend/components/quiz-card.tsx

Behavior

  • Lesson page includes description, materials (videos/articles/docs/suggestions), and a quiz.
  • Quiz evaluation uses /quiz/evaluate and shows AI feedback.
  • “Complete Lesson” button calls /progress/complete-lesson/{node_id} to award XP and update streaks.

Learning Materials (Verified Resources)

Files

  • backend/app/services/material_fetcher.py

Behavior

  • AI prompt enforces “real URL only” policy, with trust lists (YouTube channels, doc domains).
  • Filters responses and falls back to suggestions if no verified links exist.
  • Frontend displays resource cards with icon + type; suggestions appear in a yellow box.

Explain Like Child/Student/Specialist

Files

  • backend/app/services/explanation_generator.py
  • backend/app/api/v1/routes/explain.py
  • frontend/app/explain/page.tsx

Behavior

  • Single endpoint /explain/ returning child_version, student_version, expert_version.
  • Frontend UI takes a topic input and displays the three cards.

Quizzes & AI Feedback

Files

  • backend/app/api/v1/routes/quiz.py
  • backend/app/services/level_evaluator.py
  • frontend/components/quiz-card.tsx

Behavior

  • Questions are generated as part of the roadmap.
  • When user submits answers:
    • evaluate_quiz computes score, correct answers, and uses Gemini to give supportive feedback.
    • XP awarded based on percentage thresholds (>=80% double XP, >=60% standard XP).
  • Results are rendered inline on the lesson page.

Progress, XP, Streaks, Achievements

Files

  • backend/app/api/v1/routes/progress.py
  • backend/app/models/progress.py, models/lesson.py
  • frontend/components/xp-bar.tsx
  • frontend/store/progress.ts

Behavior

  • /progress/stats returns XP, streak, total lessons, achievements, and recent progress events for the dashboard.
  • /progress/completed-nodes feeds the graph to lock/unlock nodes dynamically.
  • Completing a lesson updates XP, streak, Progress table, and XP bar in the dashboard.

Profile Dashboard & Settings

Files

  • frontend/app/dashboard/page.tsx
  • frontend/components/xp-bar.tsx
  • frontend/store/progress.ts, frontend/store/user.ts
  • frontend/lib/api.ts (progress.getStats, progress.getCompletedNodes, roadmap.getAll)

Behavior

  • Dashboard is presented as a profile page: avatar with hover highlight, streak/lessons/achievements cards, and an XP bar showing level/total XP.
  • Completed lessons section pulls progress/completed-nodes and cross-references roadmap nodes to list what the learner finished (with XP reward and roadmap name).
  • Settings modal allows editing email/username/password fields (stored in the local Zustand user store today); logout now shows a confirmation dialog before clearing auth.
  • Logout CTA and settings entry are accessible in the top navigation; profile hero includes quick actions and motivational copy.
  • Settings save calls PUT /auth/me so email/username/password persist in the backend/database.

UX Notes

  • Avatar is circular with a subtle hover gray tint.
  • Logout confirmation is a modal with cancel/confirm buttons; settings modal uses shadcn-style inputs/buttons.

Roadmaps Listing & Progress

Files

  • frontend/app/roadmaps/page.tsx
  • frontend/lib/api.ts (roadmap.getAll, progress.getCompletedNodes)

Behavior

  • Shows all user roadmaps in a grid with topic, description, counts, and a green progress bar representing completed lessons percentage.
  • Progress computed from completed node IDs returned by /progress/completed-nodes against roadmap node totals.
  • Provides quick navigation back to dashboard and to each roadmap detail page.

Authentication & JWT

Files

  • backend/app/api/v1/routes/auth.py
  • backend/app/core/security.py
  • frontend/lib/api.ts (Axios interceptors + cookies)
  • frontend/app/auth/login|register/page.tsx

Behavior

  • Register/login endpoints hash passwords (Passlib/bcrypt) and issue JWTs.
  • Frontend stores access tokens in cookies (js-cookie).
  • Interceptor adds Authorization header and redirects to /auth/login when a 401 occurs.
  • Debug helper window.checkAuth() is available in dev to inspect cookie status.

Multi-language Support

Files

  • frontend/lib/translations.ts
  • frontend/store/language.ts
  • frontend/lib/useTranslation.ts
  • frontend/components/language-selector.tsx

Behavior

  • Support for English, Russian, and Kazakh.
  • Persists language choice via Zustand and displays localized labels/buttons.
  • Visual Flags: Uses flag-icons (high-resolution SVGs) to ensure accurate flag representations across all operating systems.

Tech Stack & External Dependencies

Backend

  • FastAPI, SQLAlchemy, PostgreSQL, Gemini API (google-generativeai).
  • Auth: python-jose, passlib.
  • AI abstraction: call_openai wrapper for Gemini calls.

Frontend

  • Next.js 14 (App Router), TypeScript, Tailwind, shadcn/ui.
  • State: Zustand.
  • Force Graph: react-force-graph-2d.
  • Cookies: js-cookie.
  • Flags: flag-icons.
  • Axios for API calls with interceptors.

Verified Resource Policy

  • Trusted channels: fireship, freeCodeCamp, Web Dev Simplified, Net Ninja, etc.
  • Trusted docs: MDN, react.dev, python.org, FastAPI docs, etc.
  • If uncertain, result returned as suggestion (no URL) to avoid hallucinated links.

External Links

This guide serves as a reference for high-level architecture decisions, feature ownership, and the key files involved in each major area of the app. Update this document whenever new features or external dependencies are introduced.