Get started

Your repository contains two apps: api/ (Next.js) and app/ (Expo). Use Node.js 20 or newer. Run each command from the repository root. The --prefix form keeps commands safe to paste into fresh terminals.

# API — first terminal
cp api/.env.example api/.env   # fill it in, see below
npm --prefix api install
# edit api/.env, then run this from a fresh terminal:
npm --prefix api run db:push && npm --prefix api run dev

# App (separate terminal)
cp app/.env.example app/.env   # set EXPO_PUBLIC_API_URL when needed
npm --prefix app install
# run this from another terminal:
npm --prefix app run start

The API command assumes api/.env contains a reachable Postgres DATABASE_URL, JWT_SECRET, and ENCRYPTION_MASTER_KEY. db:push creates the development schema; it cannot create the Postgres database itself. Do not run the db:push command with the example host/dbname URL still in place — create a database first, paste its real connection string into api/.env, and then run the command.

For a physical device, use your computer's LAN IP in EXPO_PUBLIC_API_URL (for example http://192.168.1.20:3001/api/v1) rather than localhost.

Use Claude Code, Codex, or another coding agent

Start the agent from the cloned repository root so it can see both api/ and app/. Before asking it to build a feature, paste this instruction:

Read AGENT.md completely before making changes. Run the project interview, use the configuration and content workflows it describes, and show me the files you plan to change before you edit them.

AGENT.md is the source of truth for the project interview, visual configuration, content pipeline, exercise templates, verification gates, and the conventions that keep AI-generated changes maintainable. The workflow is tool-agnostic: it works with Claude Code, Codex, Cursor, or another agent that can read and edit the repository.

Every deployment needs fresh secrets — generate them, don't copy from another project:

openssl rand -base64 48   # JWT_SECRET
openssl rand -hex 32      # ENCRYPTION_MASTER_KEY
openssl rand -base64 32   # CRON_SECRET

DATABASE_URL comes from a fresh Postgres database (Neon, Supabase, or local). RESEND_API_KEY is optional in dev — OTP login codes print to the API console instead of being emailed. GOOGLE_GENERATIVE_AI_API_KEY comes from aistudio.google.com/apikey.

The app is never empty on first launch — a seed course fixture ships in the repository so you can see the full loop before writing your own content. See Content pipeline to replace it.

Read AGENT.md first

If you're extending this with an AI coding agent, read AGENT.md at the repository root before generating anything — it's the working instructions for the whole codebase, including the project interview and visual configuration steps.