The learner-facing web app: course catalogue, passwordless sign-in, Stripe checkout, and video course resources.
It is one half of a pair. The backend lives in the sibling giis_strapi
repository, and almost nothing in this app renders without it running.
| Framework | Next.js 16 (App Router), React 19, strict TypeScript |
| UI | Mantine 9, CSS modules for local overrides |
| Backend | Strapi (GraphQL + REST), responses validated with Zod |
| Payments | Stripe (embedded checkout) |
| Video | Bunny Stream |
| Copy | next-intl, single en locale, no locale routing yet |
| Tests | Playwright |
| Lint / format | Oxlint and oxfmt, run on staged files by husky |
You need Node at the version in .nvmrc and npm.
nvm use
npm install
cp .env.example .env.localThen fill in .env.local. Every variable is documented inline in
.env.example; the short version:
STRAPI_URL— usuallyhttp://localhost:1337.STRAPI_API_TOKEN— printed bynpm run seed:localingiis_strapi.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY— apk_test_…key for local work.BUNNY_STREAM_*andBUNNY_PULL_ZONE— only needed for course video and Strapi-hosted images.
Never commit .env.local. When you add a required variable, add it to
.env.example too.
npm run dev # http://localhost:3000Bring these up in order. Steps 1–3 are enough to browse the app; step 4 is what makes sign-in work.
1. Seed and run Strapi. In giis_strapi:
npm run seed:local
npm run seed:startseed:local builds the fixture the app and the seeded tests expect: published
courses, cohorts, price rules, and the seed-user-01@example.test …
seed-user-10@example.test accounts. It also revokes every existing
content-API token and prints a fresh STRAPI_API_TOKEN= line — paste that
into this repo's .env.local, or every Strapi call from the web app starts
failing with an auth error.
seed:start is required here. It restores the guarded database connection
variables recorded by seed:local; a plain npm run develop starts Strapi
against the database configured in .env instead.
2. Start the mail catcher. Sign-in emails a code, so you need somewhere for it to land:
brew services start mailpitMailpit listens for SMTP on 1025 and serves its inbox UI at
http://localhost:8025. In development Strapi sends to it without
authentication.
3. Start the web app.
npm run dev4. Sign in. See below.
There are no passwords. You enter an email address, the backend mails a 6-digit code, and verifying that code creates the session cookies.
- Open http://localhost:3000/auth/login.
- Enter
seed-user-01@example.test(anyseed-user-01…seed-user-10works) and submit. - Open http://localhost:8025, open the newest message, and copy the 6-digit code.
- Type it into the 6-digit field and submit.
The account does not have to exist beforehand — a successful verification
provisions it in the default authenticated role. That is also why sign-up and
sign-in are the same flow: a first-time address lands on
/auth/complete-profile instead of the home page, because passwordless
verification has no way to collect a name, city, and country before the code
proves the address. Fill that form once and you land on /; a returning address
skips it entirely. The auth DAL's requireOnboardedUser() holds every protected
page until the profile is complete.
Reading the code without opening the Mailpit UI, newest message first:
curl -s --get http://localhost:8025/api/v1/search --data-urlencode "query=to:seed-user-01@example.test" --data-urlencode "limit=1" | python3 -c "import json,re,sys; print(re.search(r'\d{6}', json.load(sys.stdin)['messages'][0]['Snippet']).group())"Things that will bite you:
- A code expires 10 minutes after it is issued, and verifying it consumes it.
- Requesting a code again within 60 seconds is a silent no-op that sends no new mail. Always take the most recent message for the address rather than assuming a fresh one arrived.
- Five wrong attempts consume the code; request a new one.
- Use only
@example.testaddresses locally. Never sign in with a real user's email, and never point local development at non-development SMTP credentials.
Playwright drives a real browser against your running dev server. There is no
webServer block in playwright.config.ts on purpose,
so the full local stack above — Strapi, Mailpit, npm run dev — must already be
up before you run anything. Point the suite elsewhere with BASE_URL, and at a
different mail catcher with MAILPIT_URL.
npm test # the complete seed-backed suite
npm run test:seeded # the same suite, with the project explicit
npm run test:headed # watch it happen
npm run test:ui # interactive UI mode
npm run test:debug # step through with the inspector
npm run test:report # open the last HTML report
npx playwright test tests/auth # one directory
npx playwright test --project=seeded # every test in the seeded projectInstall browsers once with npx playwright install.
tests/
account/ profile details and routed account-tab behavior
api/ Strapi authentication, authorization, and exposure boundaries
auth/ sign-in and onboarding
checkout/ a real Stripe test card, end to end
course/ course pricing, enrollment states, and access
navigation/ desktop and mobile application-shell flows
public/ home, catalogue, course details, lectures, and 404s
pages/ page objects — all selectors live here
fixtures/ the shared `test` object: sign-in helpers, page objects
services/ out-of-band helpers, e.g. the Mailpit client
constants.ts seed expectations, Stripe test cards, shared timeouts
Import test and expect from @/tests/fixtures, never from @playwright/test
directly, and keep selectors in the page objects.
The fixtures do the whole passwordless dance for you, including reading the code out of Mailpit:
import { expect, test } from "@/tests/fixtures";
test("a new learner has no enrollments", async ({ signIn, accountCoursesPage }) => {
await signIn(); // provisions a fresh account and completes onboarding
await accountCoursesPage.goto();
await expect(accountCoursesPage.emptyState).toBeVisible();
});signIn(email?)runs the full flow and lands on/, filling the onboarding form when the address is new.signInWithoutOnboarding(email?)verifies the code and stops wherever that lands — use it when the onboarding step itself is what you are testing.testEmailgives each test its own uniquepw-…@example.testaddress. Do not share one address between tests: the 60-second resend window means one of them would read a code the other already consumed.mailpit.waitForLoginCode(email, afterCount?)polls for the code directly. PassafterCountwhen the address has already been mailed within the same test, otherwise you will get the previous, already-consumed code back.
Every Playwright spec runs in the seeded project against Strapi started with
npm run seed:start. The auth and checkout specs may provision isolated
throwaway accounts, but those accounts are created inside the guarded seed
database.
The course specs assert exact prices, schedules, and access states from the
fixture. The project uses one browser with fullyParallel: false because
sign-in is passwordless and two tests in one file using the same seeded account
would fight over a single emailed code. Each seeded account therefore appears
in exactly one course spec file, which keeps files safe to run in parallel.
Read tests/course/README.md before adding or moving
course scenarios.
- The checkout specs need Stripe test-mode keys and use Stripe's published
test cards from
tests/constants.ts. They are slow by design: real third-party JS plus a full sign-in. - Pages that stream resolve
redirect()on the client once the RSC payload arrives, so URL assertions need the longerSTREAMED_REDIRECT_TIMEOUT. seed.spec.tsfiles are scratch scaffolding for Playwright's test generator, not real coverage.- Test plans live in
specs/as prose, separate from the executable specs.
npm run dev # local development server
npm run build # production build
npm run start # serve an existing production build
npm run lint # Oxlint
npm run format # oxfmt
npm run typecheck # TypeScript, no emit
npm test # Playwright testsRun npm run typecheck and npm run lint before opening a PR. husky and
lint-staged already format and lint staged files on commit.
app/ route entry points, layouts, loading/error boundaries
features/<domain>/ components/ for UI, server/ for queries, schemas, services
components/ shared shell and cross-feature UI
lib/ integrations and infrastructure (api, auth)
i18n/, messages/ next-intl config and copy
proxy.ts request-time auth routing and token refresh
docs/ code style and project docs
tests/, specs/ Playwright suite and written test plans
A few conventions worth knowing before your first change: prefer Server
Components and push "use client" to the narrowest boundary that needs it; put
backend access behind service classes that validate responses with Zod; import
from the repo root with the @/ alias; and remember Server Actions are public
endpoints, so validate their input on the server even when the client already
did.
The full rules live in CLAUDE.MD (mirrored as AGENTS.MD) and
docs/code-style.md.