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.
Start here
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.
Development and verification
- Inspect the working tree, applicable agent instructions and existing
implementation before editing. Start normal work from
origin/staging on a
scoped codex/<task> branch.
- Classify the change using specs/README.md. Feature/high-risk
implementation requires the approved spec on the base branch first.
- Make a focused patch and run the affected local checks. Commands and test
boundaries are in docs/AGENT_WORKFLOW.md.
- Consolidate review findings before pushing. Open the PR against
staging.
- For an authorized production release, verify the merged staging SHA, then
promote
staging to main and verify production using the release runbook.
Install shared agent files from the repository root:
python3 backend/scripts/agent-config/install.py
The installer saves existing targets under ignored .agent-config-backups/
before linking the skills and copying the launcher/frontend guide. Git checkout
and pull do not replace your ignored agent files. Review local differences in
the backup before reusing them.
The installed Next launcher generates runtime config before starting the server.
It defaults to the canonical staging Supabase project and the local backend;
configure that backend for the same project. To use a different development
project, provide both AVER_SUPABASE_URL and AVER_SUPABASE_ANON_KEY in the
launcher environment. A partial pair is rejected before startup. The launcher
always writes the served runtime file, ignoring AVER_RUNTIME_CONFIG_OUT. Known
production origins are rejected by the generator.
Project skills cover /new-feature, /api-route, /db-migrate, /review,
/ui-review and /test. Shared instructions apply regardless of which agent
executes a task. Personal settings, credentials, generated graphs and local
verification artifacts stay ignored.
Internal project; not currently open-source.
Documentation navigation
Use the documentation map for current runbooks and historical
context, and the implementation status ledger
for outstanding feature acceptance.
Vocabulary audio
Vocabulary words and English examples use local Kokoro bf_emma (British
English), including new admin content. The web console previews stored audio;
its former OpenAI/ElevenLabs generation route returns 409 and queues nothing.
Players show a preparation or retry state instead of changing to browser speech.
With the intended Supabase environment and a local Kokoro/ffmpeg runtime:
cd backend
python -m scripts.pregen_vocab_audio # read-only inventory
python -m scripts.pregen_vocab_audio --commit # prepare missing/outdated word + example clips
The default batch compares each text's current Kokoro hash, including examples
on rows already marked final. Re-running reuses matching objects; optional
--regen rechecks every row. No other Vocabulary engine or voice is accepted.
After stamping rows, --commit invalidates Next's public:vocabulary cache tag
with the target environment's revalidation config (--no-invalidate skips it and
prints the manual command; a failed invalidation is a warning, not a batch
failure). The deployed backend's in-memory index still needs a no-op admin
PATCH /admin/vocabulary/{id} or a redeploy; verify the public URLs before acceptance.
Kokoro cache keys and synthesis use the spoken text with paired Markdown emphasis
removed; stored examples keep their display formatting. Prepare and verify audio
before publishing a set. Published sets retain snapshots, so publish a new
revision when adding recordings to a previously published set.
