How amadeusssystem/rl-tutor-project works
Project type and purpose
• This is a full-stack intelligent tutoring system combining a Next.js (React/TypeScript/Tailwind) frontend with a FastAPI (Python) backend.
• Purpose: deliver personalized learning content via a Q-Learning RL agent, track progress and analytics, support secure authentication, and provide a demo/visualization of the RL process.
File structure
• Top-level:
• app/ (Next.js “app” router) – pages, layouts, UI components, API client, contexts
• components/ui/ – reusable Tailwind/Framer Motion UI widgets
• backend/ – FastAPI service with subdirs:
– api/ (route handlers: auth, session, analytics, RL stats, recommendations)
– core/ (config, database connection, security)
– models/ (SQLAlchemy ORM, Pydantic schemas)
– services/ (RL agent, collaborative filtering, student model)
• lib/utils.ts – frontend helpers
• config files: Dockerfile, docker-compose.yml, render.yaml, tsconfig.json, ESLint, PostCSS
• docs & scripts for deployment, CI, testing, seeding DB
README insights
• Stack: Next.js 16+React 19, Tailwind v4, Aceternity UI, Framer Motion; FastAPI, SQLAlchemy, Pydantic, JWT auth, NumPy/Pandas/Scikit-learn; SQLite/ PostgreSQL
• RL agent: Q-Learning with 4D state, epsilon-greedy, custom reward
• API endpoints grouped by feature (auth, session, analytics)
• Comprehensive testing strategy: unit, integration, end-to-end
a. Frontend (Next.js)
• UI layers (pages under app/)
• Components (Navigation, Sidebar, bespoke UI in components/ui)
• Contexts (AuthContext)
• API client (app/api/client.ts)
b. Backend (FastAPI)
• HTTP API endpoints (routers in backend/app/api)
• Core services: auth & security, DB session management
• Business logic: RL agent, recommendations, learning-pace/style services
• Data layer: SQLAlchemy models and database
c. Database
• Dev: SQLite file
• Prod: PostgreSQL
• Schema (see DATABASE_SCHEMA.md)
d. External & supporting services
• JWT authentication (token issuance & refresh)
• Q-Learning in-process (no external RL engine)
• Optional: deployment environments (Docker, Vercel, Render)
• Testing harnesses (pytest, Python scripts, quick_integration_test.py)
Relationships & data flow
• User → Next.js frontend (browser)
• Frontend calls → FastAPI (HTTP/HTTPS) via client.ts
• FastAPI → Database (SQLAlchemy ORM)
• FastAPI invokes → RL services (in-memory Python modules)
• FastAPI returns → JSON (session recommendations, analytics)
• Frontend renders → UI, updates Context & state
Architectural patterns & principles
• Clear separation: presentation (frontend) vs. business logic & data (backend)
• Modular routers in FastAPI for each feature domain
• Layered architecture: API → services → data
• Stateless JWT auth with refresh tokens
• Component-based UI with Tailwind and design systems
• Single monolith for backend; monorepo structure