Intellara – AI Personal Learning Coach

Mission: Deliver a free, adaptive, multilingual learning platform that behaves like a personal tutor, planner, and progress analyst for every student.

This repository contains both the frontend (React + TypeScript + Tailwind + shadcn UI) and the planned backend (FastAPI + Supabase + Qdrant) for the Intellara platform described in the product requirements document (PRD). The long-term vision is to become the core learning intelligence for students, parents, teachers, and institutions.

---

Table of contents

1. Architecture
2. Key MVP features
3. Tech stack
4. Getting started
5. Frontend
6. Backend
7. Environment variables
8. AI + data layer
9. APIs
10. Testing & CI
11. Contributing
12. Roadmap

---

Architecture

startup/
├── frontend/          # Vite + React app (pages, components, shadcn)
├── backend/           # FastAPI services (coming online as API agents are built)
├── .github/           # Issue templates, PR template, CI workflows
└── docs/              # Architecture & contributor notes (see docs/README.md)

• Client: SPA served by Vite, routes handled by React Router, data via TanStack Query.
• Backend: FastAPI API layer exposing auth, assessment, planner, tutor, quiz, and progress endpoints (see backend/README.md).
• State & storage:
  • Supabase Auth + Postgres for profiles, plans, quiz attempts (Row Level Security enforced).
  • Qdrant vector DB for memory of mistakes, strengths, conversational context.
  • OpenRouter-powered multi-agent prompts for assessment, tutor, planner, quiz.

Key MVP features

• Supabase authentication & profile capture (name, age, education level, goals, language).
• AI skill assessment agent that runs a diagnostic quiz and persists results to memory.
• Personalized learning planner agent that adapts daily/weekly schedule.
• AI tutor agent for concept explanation, step-by-step reasoning, English/Urdu support.
• Practice & quiz agent with MCQs + short answers, difficulty scaling, instant feedback.
• Memory engine storing strengths/weaknesses and past interactions.
• Progress dashboard visualizing subject mastery and completion stats.
• Feedback loop for Easy/Hard/Confusing responses that recalibrate agents.

Tech stack

Layer	Technologies
Frontend	React 18, TypeScript, Vite, shadcn-ui, Tailwind CSS, TanStack Query, React Router
Backend	FastAPI, Pydantic, Uvicorn, Celery/RQ (future background tasks)
Auth / Data	Supabase Auth + Postgres, Supabase Storage
Memory	Qdrant (vector DB)
AI layer	OpenRouter API, multi-agent prompt orchestration
Tooling	ESLint, Prettier, Vitest, Pytest, GitHub Actions

Getting started

Prerequisites

• Node.js 18+ and npm (or bun) for the frontend.
• Python 3.11+ with pip for the backend.
• Supabase project + API keys.
• Optional: Docker + docker-compose for Postgres/Qdrant locally.

# Clone the repository
git clone <YOUR_GIT_URL>
cd startup

Frontend

Inside frontend/:

npm install          # or bun install
env-cmd -f .env npm run dev   # Vite dev server on http://localhost:5173
npm run build        # Production build
npm run lint         # ESLint
npm run test         # Vitest (if enabled)

Key folders:

• src/pages – Landing, auth, dashboard, tutor, learning plan, quiz, profile.
• src/components – shadcn UI, layout, auth forms, navigation, hero sections.
• src/lib – Supabase client, helpers.
• public/intellara-logo.svg – Animated crest embedded in navbar/auth/hero.

Read more in frontend/README.md.

Backend

The backend is scaffolded in backend/ and will expose the following modules:

• auth – Supabase session verification + profile bootstrap.
• assessment – Diagnostic quizzes, Qdrant memory updates.
• planner – Generates/updates study plans, syncs with Supabase tables.
• tutor – Chat/completions pipeline using OpenRouter.
• quiz – On-demand practice sets & grading callbacks.
• progress – Aggregations for dashboards, badge logic.

Common commands (see backend/README.md):

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn main:app --reload
pytest
ruff check && mypy

Environment variables

Create .env files both in frontend/ and backend/ (never commit secrets).

Frontend .env

VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=
VITE_OPENROUTER_KEY=
VITE_QDRANT_URL=

Backend .env

SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
QDRANT_URL=
QDRANT_API_KEY=
OPENROUTER_KEY=

AI & data layer

1. Skill assessment agent – Creates question set, scores answers, stores embeddings.
2. Learning planner agent – Uses assessment results + feedback to generate schedule.
3. Tutor agent – Conversation memory stored in Qdrant, multi-lingual responses.
4. Quiz agent – Generates difficulty-scaled MCQs and short answers, returns hints.
5. Feedback loop – Students mark Easy/Hard/Confusing, planner adjusts difficulty.

APIs

Endpoint	Method	Description
/auth/login	POST	Email/password login via Supabase
/student/profile	POST	Create/update student profile
/assessment/start	POST	Run diagnostic, persist in Qdrant
/learning/plan	POST	Generate/update study plan
/tutor/chat	POST	Chat with AI tutor (streaming)
/quiz/generate	POST	Create quiz session based on weaknesses
/progress/summary	GET	Dashboard metrics

Testing & CI

GitHub Actions live in .github/workflows/:

• frontend-ci.yml – npm ci, lint, build, vitest.
• backend-ci.yml – pip install, Ruff lint, mypy, pytest.

Local testing commands mirror the workflow steps. Keep them green before opening a PR.

Contributing

1. Fork & clone the repo.
2. Create a feature branch (feat/tutor-ui).
3. Follow the Pull Request Template.
4. Ensure lint/tests pass locally and in CI.
5. Use the issue templates for bugs/features. Larger items should link back to the PRD.

See docs/CONTRIBUTING.md for more detail on coding standards, commit naming, and design expectations.

Roadmap

• ✅ Animated brand identity shared between landing, navbar, and auth flows.
• 🚧 Wire backend FastAPI services + Supabase integration.
• 🚧 Implement multi-agent orchestration (assessment, tutor, planner, quiz).
• 🚧 Add progress dashboards, localized content, and parent/teacher views.
• 🔮 Future: voice tutor, offline mode, licensing for institutions, certification system.

---

Need help? Open an issue using the templates or ping the maintainers listed in CODEOWNERS. Let’s build the AI Learning Operating System together. ✨

Intellara---AI-Learning-System-

Intellara---AI-Learning-System-