76 lines
5.9 KiB
Markdown
76 lines
5.9 KiB
Markdown
# 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**, backed by **PocketBase** as the database and auth layer.
|
|
* **Frontend:** React, React Router, Tailwind CSS.
|
|
* **Backend:** PocketBase (self-hosted). All data is stored in PocketBase collections, not localStorage.
|
|
* **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)
|
|
All persistent data lives in **PocketBase**. The data access layer is in `src/lib/db.js`, which wraps the PocketBase SDK client from `src/lib/pb.js`.
|
|
|
|
**PocketBase Collections:**
|
|
* `topics` — Knowledge graph nodes (`id`, `label`, `type`, `description`).
|
|
* `relations` — Knowledge graph edges (`source`, `target`, `type`).
|
|
* `content` — AI-generated learning modules per topic (`topic_id`, `data`).
|
|
* `quiz_banks` — Banks of AI-generated questions per topic (`topic_id`, `questions[]`).
|
|
* `quiz_results` — User test scores (`user_id`, `week_number`, `score`, `total`, `percentage`, etc.).
|
|
* `quiz_cache` — Cached weekly quiz for a user (`user_id`, `week_number`, `questions[]`, `meta`).
|
|
* `learn_progress` — Whether a user completed the weekly learning session (`user_id`, `week_number`, `done`).
|
|
* `leaderboard` — Points ledger (`user_id`, `name`, `points`, `tests_completed`).
|
|
* `team_members` — Registered users with PIN auth (`name`, `role`, `pin`).
|
|
* `sources` — Uploaded source documents and their extraction status (`name`, `status`, `error`).
|
|
* `settings` — Key/value store for app-wide settings (`key`, `value`).
|
|
|
|
**localStorage** is only used for **admin browser settings** (not user data):
|
|
* `respellion:admin:anthropic_key` — Anthropic API key.
|
|
* `respellion:admin:model` — Model override.
|
|
* `respellion:admin:use_simulation` — Simulation mode toggle.
|
|
|
|
**Session:** User login is PIN-based. The logged-in user's ID is stored in `sessionStorage` under `respellion_session` and resolved against `team_members` on app load (see `src/store/AppContext.jsx`).
|
|
|
|
**Important:** All `db.js` functions are `async`. Always `await` them — omitting `await` will silently pass a Promise where data is expected.
|
|
|
|
**Auto-Cancellation:** The PocketBase JS SDK has auto-cancellation enabled by default. This causes concurrent identical requests (like `db.getTopics()` during React StrictMode renders or concurrent Promise.all) to abort with `ClientResponseError 0`. This feature is **globally disabled** in `src/lib/pb.js` via `pb.autoCancellation(false)` to prevent UI crashes during concurrent fetching.
|
|
|
|
## 3. The AI Integration (Anthropic)
|
|
The application calls the Anthropic API via a proxy to avoid CORS issues.
|
|
* **Location:** `src/lib/api.js`.
|
|
* **Proxy:** In Docker, `/api/anthropic` is proxied via Nginx to the Anthropic API endpoint. In local dev, configure `vite.config.js` to proxy the same path.
|
|
* **JSON Enforcement:** Prompts *must* strictly enforce that Claude returns *only* raw JSON. Do not let the AI wrap the response in markdown blocks — a regex strip via `.match(/\{[\s\S]*\}/)` is already applied in all service files.
|
|
|
|
## 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 (handled in `testService.js → saveTestResult`).
|
|
* A 100% score grants the **Perfectionist** badge (computed at render time in `Leaderboard.jsx`).
|
|
* Completing 1 test grants **First Steps**, completing 5 grants **Veteran**.
|
|
* Points are accumulated in the `leaderboard` collection via `db.upsertLeaderboardEntry`.
|
|
|
|
## 6. Docker & Deployment
|
|
The app is fully containerized. PocketBase runs as a sidecar service.
|
|
* **Build:** `docker build -t respellion-app:latest .`
|
|
* **Run:** `docker compose up -d` (see `docker-compose.yml`).
|
|
* **Nginx:** Ensures any frontend route not matching a static file falls back to `index.html` (SPA support). The `/api/anthropic` path is proxied to the Anthropic API. The `/pb` path is proxied to the PocketBase service.
|
|
* **PocketBase URL:** Resolved from `VITE_PB_URL` env var, or falls back to `window.location.origin + '/pb'` (see `src/lib/pb.js`).
|
|
|
|
## 7. How to Add New Features
|
|
1. **Define Schema:** Add a new PocketBase collection via the Admin UI or the init script (`scripts/setup-pb-collections.mjs`).
|
|
2. **Add DB Helpers:** Add async CRUD functions in `src/lib/db.js`.
|
|
3. **Build UI:** Create components using `Card`, `Button`, and `framer-motion` for smooth entry (`animate-in fade-in slide-in-from-bottom-4`).
|
|
4. **Wire Logic:** Connect to `src/store/AppContext.jsx` if it requires global user context, otherwise manage state locally.
|
|
5. **Test:** Run the Docker stack (`docker compose up`) 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.
|