learning-platform/AI_AGENT.md

AI Agent Context Guide: Respellion Learning Platform

Welcome, fellow AI agent! If you are reading this, you are tasked with maintaining or extending the Respellion Learning Platform. This document provides the critical context, architectural patterns, and design standards you need to successfully work on this codebase.

1. Architectural Overview

This is a single-page React application built with Vite. It is completely self-contained and currently runs without a dedicated backend database.

• Frontend: React, React Router, Tailwind CSS.
• Animations: Framer Motion (used extensively for page transitions, podium effects, and gamification feedback).
• Icons: Lucide React.
• Visualizations: D3.js (used strictly for the Admin Knowledge Graph).

2. State Management & Storage (Critical)

There is no backend database. All data is persisted locally in the browser using a custom wrapper around window.localStorage located at src/lib/storage.js.

Namespacing Convention: You must strictly adhere to these prefixes when reading/writing to storage.js:

• kb:* - Knowledge base data (e.g., kb:topics, kb:relations, kb:content:{topicId}).
• admin:* - Admin settings (e.g., admin:anthropic_key, admin:sources, admin:use_simulation).
• user:{id}:* - Specific user progress (e.g., user:{id}:week:{n}:learn_done).
• quiz:bank:{topicId} - Cached banks of AI-generated multiple-choice questions.
• quiz:result:{userId}:week:{n} - The exact score and payload of a user's weekly test.
• leaderboard:current - The active points ledger. Array of objects: { userId, name, points, testsCompleted, perfectScores }.
• users:registry - Array of registered users, including admins.

3. The AI Integration (Anthropic)

The application acts as a proxy to the Anthropic API (claude-sonnet-4).

• Location: src/lib/api.js.
• Proxy: In Docker, /api/anthropic is proxied via Nginx to bypass CORS restrictions. If the user reports CORS errors during local dev, ensure the Vite proxy in vite.config.js matches the Nginx spec.
• JSON Enforcement: Prompts must strictly enforce that Claude returns only raw JSON. Do not let the AI wrap the response in markdown blocks (\``) unless you build a regex to strip them (which is currently implemented via .match(/{[\s\S]*}/)`).

4. Design System & Aesthetics

Respellion relies on a premium, modern aesthetic.

• CSS Variables: Rely heavily on the variables defined in src/index.css.
  • Colors: var(--color-bg), var(--color-paper), var(--color-teal), var(--color-accent).
  • Radii: var(--r-sm), var(--r-lg), var(--r-org) (an organic, pill-like shape used for badges and podiums).
• Tailwind: Tailwind is mapped to these CSS variables. Avoid hardcoding random hex codes. Use the existing Tailwind classes like bg-teal, text-fg-muted, and border-bg-warm.
• Components: Always reuse the UI primitives in src/components/ui/ (Card.jsx, Button.jsx, Tag.jsx, Input.jsx).

5. Gamification Rules

If you are extending the Gamification system (src/pages/Leaderboard.jsx):

• Tests grant +2 points per correct answer.
• A 100% score grants the Perfectionist badge.
• Completing 1 test grants First Steps, completing 5 grants Veteran.
• Do not reset points dynamically. Read from leaderboard:current, mutate, and save back immediately.

6. Docker & Deployment

The app is fully containerized.

• Build: docker build -t respellion-app:latest .
• Run: docker run -d -p 8080:80 --name respellion respellion-app:latest
• Nginx: Ensure any new frontend routes are caught by the Nginx try_files $uri $uri/ /index.html; directive defined in nginx.conf to prevent 404s on page refresh.

7. How to Add New Features

1. Define State: Decide where the data lives in localStorage.
2. Build UI: Create components using Card, Button, and framer-motion for smooth entry (animate-in fade-in slide-in-from-bottom-4).
3. Wire Logic: Connect to src/store/AppContext.jsx if it requires global user context, otherwise manage locally and persist to storage.js.
4. Test: Run the Docker container to ensure no build errors exist.

Good luck! You are building a platform that empowers continuous learning. Keep it fast, keep it beautiful, and keep the user engaged.