🤖 AI Quest

An interactive, AI-powered quiz game that tutors students on Artificial Intelligence concepts — built with React and powered by the Anthropic Claude API.

---

✨ Features

• Infinite AI-generated questions — Claude generates fresh, unique questions every session; no static question bank.
• 5 topic areas — AI Basics, Machine Learning, Language Models, AI Ethics, Advanced AI.
• 3 difficulty levels — Beginner, Intermediate, Expert.
• Personalised feedback — Claude analyses your session results and writes tailored study guidance.
• XP system — Earn points for correct answers across sessions.
• Repeat-question avoidance — Previously asked questions are sent back to the model to prevent duplicates.

---

🛠 Tech Stack

Layer	Technology
UI framework	React 18 (functional components + hooks)
Build tool	Vite 5
AI backend	Anthropic Claude API (/v1/messages)
Styling	Inline React styles + CSS keyframes
Fonts	Google Fonts (Syne, Space Mono)
Linting	ESLint + eslint-plugin-react-hooks

---

🚀 Getting Started

Prerequisites

• Node.js ≥ 18 and npm ≥ 9
• An Anthropic API key

Installation

# 1. Clone the repository
git clone https://github.com/your-org/ai-quest.git
cd ai-quest

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env and set VITE_ANTHROPIC_API_KEY=sk-ant-...

# 4. Start the development server
npm run dev

Open http://localhost:5173 in your browser.

Build for Production

npm run build
npm run preview   # preview the production build locally

⚠️ Production Warning — See Security Considerations before deploying.

---

🗂 Project Structure

ai-quest/
├── public/                  # Static assets
├── src/
│   ├── components/
│   │   └── Particles.jsx    # Celebratory particle burst component
│   ├── constants/
│   │   └── game.js          # Centralised game config (topics, difficulties, XP)
│   ├── hooks/
│   │   └── useQuiz.js       # All game state & logic (testable, framework-agnostic)
│   ├── utils/
│   │   └── api.js           # Anthropic API helpers with input validation
│   ├── AITutorGame.jsx      # Root component — screen routing only
│   └── main.jsx             # React entry point
├── docs/
│   └── security-notes.md    # Extended security documentation
├── .env.example             # Environment variable template (safe to commit)
├── .gitignore
├── package.json             # Pinned dependencies
├── SECURITY.md              # Vulnerability disclosure policy
└── README.md

---

⚙️ Configuration

All configuration is via environment variables. Copy .env.example to .env:

Variable	Required	Default	Description
VITE_ANTHROPIC_API_KEY	✅ Yes	—	Your Anthropic API key
VITE_CLAUDE_MODEL	No	claude-sonnet-4-20250514	Claude model to use
VITE_MAX_TOKENS	No	1000	Max tokens per API response
VITE_TOTAL_QUESTIONS	No	5	Questions per quiz session (1–20)

---

🔒 Security Considerations

API Key Exposure (Important)

This project is a client-side React app, which means VITE_ANTHROPIC_API_KEY is embedded in the compiled JavaScript bundle. Anyone who inspects the network requests or bundle can read the key.

For any public or production deployment, you must:

1. Create a server-side proxy (e.g. an Express route, Next.js API route, or serverless function) that holds the API key and forwards requests to Anthropic.
2. Remove VITE_ANTHROPIC_API_KEY from the frontend entirely.
3. Add rate limiting and authentication to the proxy endpoint.

This architecture is safe for local development and internal tools where the audience is trusted.

Prompt Injection

• Topic and difficulty values are sourced from closed constant lists — they are never taken from free-form user input.
• All user-influenced values are sanitised (length-capped, type-checked) before being included in prompts.
• Model responses are structurally validated before use; malformed output causes a visible error rather than silent failure.

Input Validation

• Prompts are capped at 8000 characters.
• API responses are validated for expected shape before any data is rendered.

See docs/security-notes.md for the full security architecture.

---

🤝 Contributing

1. Fork the repository and create a feature branch: git checkout -b feat/my-feature
2. Follow existing code style — components stay thin, logic lives in hooks/utils.
3. Never commit .env or any real credentials.
4. Open a pull request with a clear description of the change and its motivation.
5. Ensure npm run lint passes with zero warnings before submitting.

Please read our Code of Conduct before contributing.

---

📄 License

MIT © Your Organisation. See LICENSE for details.