# Repository Notes

## Next.js

This repository uses Next.js 16 with breaking changes relative to earlier versions. Read the relevant guide in `node_modules/next/dist/docs/` before changing framework code and heed deprecation notices.

## Shape

- The Next.js application lives at the repository root and uses the App Router, React 19, TypeScript, and `output: "standalone"`.
- Pages, `GET /api/events`, and health routes run in one Node.js process.
- Calendar data is fetched at runtime from an external ICS source.
- TSX content modules live under `src/trip-reports/` and are registered in `src/trip-reports/index.ts`.

## Commands

- Install dependencies exactly as CI does: `npm ci`.
- Checks: `npm run lint`, `npm run typecheck`, `npm run test`, `npm run build`.
- E2E smoke test: `npm run test:e2e`.
- Dev server: set `CALENDAR_URL`, then run `npm run dev`.

## Configuration and assets

- `.env.example` documents safe example settings.
- `CALENDAR_URL` is required at runtime but not during `next build`.
- `APP_URL` controls canonical URLs, sitemap, robots, host checks, and the default CORS origin.
- Original image sources live in `.media-source/`; generated variants live under `public/images/`.
- Use `npm run content:new` for new TSX content modules.

## CI and deployment

- Workflows live in `.gitea/workflows/`.
- CI runs lint, Vitest, typecheck, build, E2E, and security scans.
- Deploy builds and scans a configurable container image, deploys with Docker Compose, verifies app/API/health routes, and supports rollback.