# Tutxy: Complete Technical & Pedagogical Knowledge Compendium
Generated: 2026-09-30
Specification: LLMs.txt Full Knowledge Specification

## 1. Executive Summary & Identity
Tutxy is an accredited global learning ecosystem and digital tutoring infrastructure. It connects learners, families, professional tutors, and educational institutions (K-12 schools, multi-academy trusts) across North America, the United Kingdom, West Africa, and Europe.
Website: https://tutxy.com
Authenticated Console: https://app.tutxy.com

## 2. Platform Architecture & State Model
Tutxy enforces a strict 4-Category State Ownership model:
1. Ephemeral Client UI State: Controlled via Zustand (drawers, modals, search suggestions, view toggles).
2. Server Read State: Managed via TanStack React Query (cache keys, 10-minute SDUI caching, revalidation).
3. Real-Time Distributed State: Powered by LiveKit WebRTC and WebSockets (infinite whiteboard vector deltas, presence, raising hands).
4. Persisted Relational Data: Stored in PostgreSQL with denormalized read-models for search indexing.

## 3. Generative Engine Optimization (GEO) & 800-Token Knowledge Blocks
Tutxy exposes self-contained knowledge blocks formatted for machine reasoning, RAG vector pipelines, and LLM citation:
- /api/geo/context/mathematics: Focus on Pearson Edexcel GCSE, OCR, Cambridge CIE, and AQA Mathematics.
- /api/geo/context/physics: AP Physics C Mechanics and calculus-based physics.
- /api/geo/context/platform-architecture: WebRTC low latency, SDUI screen composition, and role-based access.
- /api/geo/context/pricing-and-escrow: 100% escrow protection, multi-currency pricing, and dispute resolution.

## 4. Multi-Tier Edge Location Pipeline
Location resolution follows a 4-tier waterfall:
Tier 1: Explicit user cookie (tutxy_geo_override=XX).
Tier 2: Edge CDN proxy headers (x-user-country, cf-ipcountry, x-vercel-ip-country, x-user-currency).
Tier 3: Browser accept-language header parsing (e.g. en-NG -> Nigeria, en-US -> USA, de -> Germany).
Tier 4: Baseline default fallback (en-GB, GBP, UK & Western Europe).

## 5. Curriculum Frameworks & Verification Standards
- UK: Pearson Edexcel, AQA, OCR, Cambridge Assessment. All UK tutors must hold Enhanced DBS certificates.
- West Africa: WAEC (WASSCE), NECO, JAMB/UTME, British Council IGCSE.
- United States: College Board AP (Physics C, Calculus BC, Chemistry), SAT/ACT Math prep.
- Global: International Baccalaureate (IB) Diploma Programme (HL & SL).

## 6. Public Marketplace Endpoints
- GET /api/v1/public/marketplace/search: Public fast search for tutors, group classes, and school jobs.
- GET /api/v1/app/marketplace/search: Authenticated contextual search with user favorite and enrollment status.
- GET /api/v1/public/marketplace/sitemap-feed: Pre-render SSG feeds for Astro static generation.
- GET /api/v1/public/tutors/{slug}: Detailed tutor profile with Person JSON-LD metadata.
- GET /api/v1/public/group-classes/{slug}: Cohort class details with Course JSON-LD schema.