PhiloMind

PhiloMind is a monorepo for an AI-assisted philosophy learning product. It turns a linear course into a guided journey with a learner frontend, an admin portal, a NestJS API, PostgreSQL/Supabase storage, AI-assisted debate and podcast generation, flashcards, quizzes, and a FastAPI TTS worker.

This repository should be read from the current code first. Historical proposal files, old frontend optimization reports, and copied lesson code dumps were removed because they no longer matched the running architecture.

Services

Service	Path	Stack	Default port	Role
Learner frontend	frontend/	React 18, Vite, Tailwind, TanStack Query	3000	Student-facing journey, lesson player, practice, debate, settings
Admin portal	admin/	React 18, Vite, Tailwind	3002	CRUD for users, courses, nodes, practice content, debates, Philosofun
Backend API	backend/	NestJS 11, Prisma, PostgreSQL, Supabase JS	3001 or 7860 on Hugging Face	Auth, roadmap, lesson flow, progress, AI, storage, TTS proxy
TTS worker	tts_worker/	FastAPI, Kokoro ONNX, fallback WAV generator	8000 or 7860 on Hugging Face	Text-to-speech synthesis for podcast previews
Local DB	docker-compose.yml	PostgreSQL 15 with pgvector image	5432	Local development database

Canonical Docs

Start here:

• Full project specification (Vietnamese) - complete tech + non-tech spec: product goals, curriculum, features, architecture, data model, ops, in one document.
• Project overview - current architecture, modules, data model, and major flows.
• API reference - current endpoint inventory generated from controller inspection; use Swagger /docs for live schemas.
• Lesson components - detailed lessonFlow, lessonMedia, renderer, validator, progress, and authoring contract.
• Operations - environment variables, local setup, Supabase/Postgres pooling, deployment, security, and post-deploy checks.
• Design system - current product UX principles and frontend layout conventions.

Module docs:

• Backend
• Learner frontend
• Admin portal
• TTS worker

Local Development

Copy the root env template and fill real secrets:

cp .env.example .env

Run the full local stack:

docker compose up --build

Run services manually when debugging a single layer:

cd backend && npm install && npx prisma generate && npm run start:dev
cd frontend && npm install && npm run start
cd admin && npm install && npm run start
cd tts_worker && pip install -r requirements.txt && python main.py

The backend API uses global prefix /api. Root health endpoints are outside the prefix: / and /health. Swagger is available at /docs outside production, or when ENABLE_SWAGGER=true.

Verification

Common checks:

cd backend && npm run test -- --runInBand
cd frontend && npm run test -- --run && npm run build
cd admin && npm run test -- --run && npm run build

CI runs backend tests plus frontend/admin test and build verification on GitHub Actions.