Sudar — Cursor Rules

# Sudar — Cursor Rules
# Learning Operating System | "Learns with you, for you."

## ALWAYS READ ECOSYSTEM.md FIRST
Before making any changes, read ECOSYSTEM.md and AGENTS.md in the Sudar root directory.
These files contain the authoritative architecture, naming conventions, and build decisions.
Before adding features, check **docs/STRATEGIC_PATH.md** for current state and prioritized next steps. For the current "Next 3" outcomes, read **PROGRESS.md**.
For decisions, glossary, feature map, and known gaps, read **docs/memory/** (start at `docs/memory/README.md`). Known traps: `.cursor/rules/sharp-edges.mdc`.

Before marking **user-visible** or **operator-facing** work complete, apply **docs/SHIP_MEMORY_PLAYBOOK.md** and update **UPDATES.md** / **docs/SHIPPED_FEATURES.md** (see **.cursor/rules/sudar-ship-memory.mdc** and **AGENTS.md**).

---

## Project Identity
- Product name: Sudar
- Admin surface: Sudar Studio (in /sudar-studio)
- Learner surface: Sudar Learn (in /sudar-learn)
- AI engine: Sudar Intelligence (in /sudar-intelligence)
- AI Tutor name: "Sudar" (never change this name)
- Mission: "Learns with you, for you."

---

## Tech Stack (Do Not Deviate)
- Frontend: Next.js 15 (App Router), TypeScript 5, Tailwind CSS 3
- Database: Supabase PostgreSQL via `@supabase/ssr` + service-role clients (Prisma folders are leftovers, not used at runtime); canonical DDL in `supabase/migrations/`
- Auth: Supabase Auth (shared across Studio + Learn)
- State: Zustand for complex client state
- Animation: Framer Motion
- AI providers (see `shared/ai/platformChat.ts`): org BYOM / Sudar AI runtime first, then OpenRouter -> Together AI -> OpenAI -> Anthropic
- Backend AI: Python 3.11+ FastAPI
- Video: Python + FFmpeg + Edge-TTS + Remotion

---

## TypeScript Rules
- Always use strict TypeScript — no `any` types
- Define all shared types in the `types/` directory
- Use Zod for API payload validation
- Prefer Server Components; only use "use client" when required for interactivity
- Use `@/` path alias for all project-relative imports

---

## Styling Rules
- Tailwind CSS only — no inline styles, no external CSS libraries (CSS modules allowed only for complex animations, e.g. `SudarVoiceOrb.module.css`)
- Follow mobile-first responsive design on all learner-facing components
- Dark mode support must be included for all new components
- Use CSS variables for brand colors (defined in tailwind.config.ts)
- Sudar design tokens: primary brand is deep blue-purple, accent is electric cyan

---

## Database Rules
- All Supabase queries on the server use the SERVICE ROLE key
- All Supabase queries on the client use the ANON key
- Never expose the service role key to the browser
- Always use Row Level Security (RLS) policies on all tables
- Every table must have `created_at timestamptz DEFAULT now()`
- Use `gen_random_uuid()` for all primary keys

---

## API Route Rules
- API routes live in `app/api/` using Next.js App Router
- Always validate request bodies with Zod before processing
- Return consistent JSON: `{ success: boolean, data?: any, error?: string }`
- All authentication checks at the top of every API route
- Rate limiting on all public-facing AI endpoints

---

## AI Integration Rules
- Always go through the shared chat helpers (`chatCompletion` -> `shared/ai/platformChat.ts`), which apply the provider fallback chain
- Log tutor exchanges to the `ai_interactions` Supabase table
- Never expose AI API keys to the client
- Implement exponential backoff on retry (max 3 attempts)
- Authored content must pass the quality gate before it is stored: Zod schema, `moderateContent()` (Llama Guard via Together, OpenAI moderation fallback), rubric score + regeneration. See `.cursor/rules/content-generation.mdc` and `docs/CONTENT_QUALITY.md`

---

## Event Tracking Rules
- Every learner interaction MUST write a record to `learning_events`
- Event types: module_start, module_complete, quiz_attempt, modality_switch,
  ai_tutor_open, ai_tutor_query, video_play, video_pause, drop_off
- Include `modality` field on all events (which format was active)
- Never batch events — write immediately for real-time adaptive engine

---

## Component Architecture Rules
- Atomic design: atoms → molecules → organisms → templates → pages
- Co-locate component tests with the component file
- Extract reusable hooks into `hooks/` directory
- Never put business logic in UI components — use hooks and lib functions

---

## Code Quality Rules
- No console.log in committed code (use a logger utility instead)
- No hardcoded strings — user-facing copy in constants files
- No hardcoded IDs (org IDs, user IDs, course IDs)
- No TODO comments without an associated GitHub issue reference
- All async operations must handle loading, error, and empty states in the UI
- Accessibility: all interactive elements need aria-labels, keyboard navigation

---

## Comments Policy
- Only add comments that explain WHY, not WHAT (the code explains what)
- Explain non-obvious business logic (e.g. why a specific adaptive algorithm threshold was chosen)
- Never add comments that just narrate the code ("// increment counter", "// return result")

---

## File Organization (sudar-studio and sudar-learn)
```
app/
  (auth)/          — auth pages (login, register, onboarding)
  (dashboard)/     — main authenticated pages
  api/             — API routes
components/
  ui/              — primitive UI components (Button, Input, Card...)
  features/        — feature-specific components
hooks/             — custom React hooks
lib/
  supabase/        — Supabase client + server instances
  ai/              — AI provider clients and utilities
  utils/           — general utility functions
types/             — TypeScript type definitions
constants/         — app constants and copy strings
```

---

## When Adding a New Feature
1. Check ECOSYSTEM.md to see if it's planned or conflicts with architecture
2. Determine: Studio (admin) or Learn (learner)?
3. Create the Supabase migration if new tables are needed
4. Add the feature to the appropriate surface
5. Ensure `learning_events` is written to if learner-facing
6. Test mobile layout if learner-facing
7. Update ECOSYSTEM.md Phase checklist if it completes a milestone
8. If user-visible or operator-facing: update **UPDATES.md** / **docs/SHIPPED_FEATURES.md** per **docs/SHIP_MEMORY_PLAYBOOK.md** (same PR unless user defers)

---

## Ship memory (user-facing or operator-facing work)

When a feature is merge-ready and affects learners, admins, deployers, or public APIs, follow **docs/SHIP_MEMORY_PLAYBOOK.md** and update **UPDATES.md** / **docs/SHIPPED_FEATURES.md** as described there before considering the task complete. Rule: **.cursor/rules/sudar-ship-memory.mdc** (`alwaysApply: true`).

---

*Sudar | v1.0 | April 2026*