Aver Learning · IELTS Speaking Coach

IELTS and English practice across Speaking, Writing, Reading, Listening, Vocabulary, Grammar Wiki, Courses and Mock Tests. The repository retains its original Speaking Coach name.

• Production: averlearning.com
• Staging: staging.averlearning.com
• Stack: Next.js 16 App Router + React 19 + TypeScript on Vercel; FastAPI on Railway; Supabase PostgreSQL, Auth and Storage.
• Product map: docs/SITE_OVERVIEW.md.

Start here

Document	Purpose
AGENTS.md	Shared working agreement and domain invariants for every agent
CLAUDE.md	Project navigation and implementation context
docs/AGENT_WORKFLOW.md	Worktrees, verification, handoff and completion evidence
specs/README.md	Active feature intent, change classes and spec lifecycle
docs/STAGING_FIRST_RELEASE_FLOW.md	Staging verification and production promotion
backend/migrations/README.md	Migration numbering, forward policy and ledger

Historical plans and audits explain earlier decisions. Current instructions, active specs, code and executable tests govern new work; a historical checklist does not prove that a release is pending or complete.

Repository layout

• frontend/app/ — deployed App Router pages and route groups.
• frontend/components/, frontend/lib/, frontend/types/ — shared React UI, API/auth boundaries and generated OpenAPI types.
• frontend/public/ — static assets and remaining compatibility controllers. Retired HTML under frontend/tests/fixtures/legacy-html-retired/ is test evidence; root HTML aliases are not deployment sources.
• backend/main.py, backend/routers/, backend/services/ — FastAPI entry, authenticated domain APIs and business logic.
• backend/content/, backend/migrations/, backend/tests/ — content, schema changes and backend tests.
• specs/ — active specifications; docs/ — runbooks, product map and history.
• backend/scripts/agent-config/ — versioned project skills and local config templates. Install them explicitly to the ignored agent paths; existing files are backed up.

Local setup

Use Node.js 24+ (frontend/package.json). Backend CI uses Python 3.11; Railway builds with Railpack from the backend/ directory only (service root directory); Python 3.12 is pinned there through the service's RAILPACK_PYTHON_VERSION variable. Anything the backend reads at runtime (for example backend/assets/grammar-mindmap/) must live under backend/. Use either of those Python versions locally. Audio processing also requires ffmpeg; production additionally needs default-jre-headless (LanguageTool) and fonts-dejavu-core (PDF export). backend/nixpacks.toml lists those packages for the legacy Nixpacks builder, but Railpack does not read it — the Railway service configuration must provide them. Verify in the Railway dashboard, not from this file, before relying on them.

Configure a development or staging Supabase project and the provider keys needed for the flow you are exercising. Keep service credentials in ignored environment files. The browser receives only the Supabase public/anon key.

Backend, from the repository root:

python3 -m venv backend/venv
source backend/venv/bin/activate
python -m pip install -r backend/requirements.txt
cp backend/.env.example backend/.env
# Edit backend/.env for the intended non-production environment.
cd backend
python -m uvicorn main:app --reload --port 8000

/docs, /redoc and /openapi.json return 404 unless ENABLE_API_DOCS=1 is set in backend/.env (local development only; staging and production leave it unset). CI builds the schema in process with app.openapi().

Frontend, in a separate terminal from the repository root:

cd frontend
npm ci
export VERCEL_ENV=development
export AVER_ENVIRONMENT=test
export AVER_API_BASE=http://localhost:8000
export AVER_SUPABASE_URL=https://YOUR-DEV-PROJECT.supabase.co
export AVER_SUPABASE_ANON_KEY=YOUR-DEV-PUBLIC-KEY
unset AVER_RUNTIME_CONFIG_OUT
node tooling/generate-runtime-config.mjs && npm run dev

Open http://localhost:3000. VERCEL_ENV=development enables the generator's production-origin guard. AVER_ENVIRONMENT=test admits the local API origin in the development CSP. The generator receives shell variables; it does not load .env.local itself. Use the same Supabase project as the backend. predev copies vendor bundles but does not regenerate runtime config. After local use, restore the committed unconfigured default before committing:

env -u VERCEL_ENV -u VERCEL_GIT_COMMIT_SHA -u VERCEL_GIT_COMMIT_REF \
  -u AVER_ENVIRONMENT -u AVER_API_BASE -u AVER_SUPABASE_URL \
  -u AVER_SUPABASE_ANON_KEY -u AVER_CORE_OPERATION_CORRELATION_ENABLED \
  -u AVER_WRITING_ADMISSION_ENABLED -u AVER_RUNTIME_CONFIG_OUT \
  node tooling/generate-runtime-config.mjs

Database setup depends on the target's schema and migration ledger. Follow the migration guide and use backend/scripts/apply_migrations.sh for forward changes. Do not replay the numbered directory with a shell loop or baseline an existing database to hide drift. Migrations are separate from application auto-deploys.

When changing the committed static Tailwind CSS, install its separate locked toolchain in the current checkout before rebuilding:

cd frontend
npm run build:css:setup
npm run build:css

Dependency directories stay ignored. Do not commit a node_modules symlink or an absolute path to another checkout. CI installs this same isolated toolchain and checks that the generated CSS matches the committed files.

This is the beginning of the README. Read the rest at the original. Read the full README ↗