# Repository Guidelines

## Project Structure & Module Organization

This repository contains the Next.js application for the Chadebebe wishlist site. App Router routes live in `app/`, including public wishlist pages in `app/[slug]/`, admin screens in `app/admin/`, and API handlers in `app/api/`. Shared UI belongs in `components/`, while server utilities, auth, database access, and scraping helpers live in `lib/`. Drizzle and SQLite data are under `lib/db/` and `data/db/`. Static assets are in `public/`; uploaded runtime assets are stored in `data/uploads/`. Deployment configuration is in the parent project root at `/home/adriano/chadebebe/docker-compose.yaml`, which builds this `src/` directory.

## Build, Test, and Development Commands

Run commands from `src/` unless noted.

- `npm install`: install local dependencies.
- `npm run dev`: start Next.js locally on port `3000`.
- `npm run build`: create the production Next.js standalone build.
- `npm run lint`: run the configured Next.js ESLint command.
- `npm run db:migrate`: apply Drizzle migrations.
- `npm run db:studio`: open Drizzle Studio for database inspection.
- `npm run guest:create -- --name="Name"`: create a guest access token.
- From `/home/adriano/chadebebe`, `docker compose up -d --build`: rebuild and redeploy the production container.

## Coding Style & Naming Conventions

Use TypeScript, React function components, and the App Router conventions already present in `app/`. Keep indentation at two spaces. Prefer descriptive camelCase for variables/functions, PascalCase for components, and lowercase route directory names. Keep UI copy in Portuguese for user-facing screens. Use Tailwind CSS utility classes for styling and follow existing component patterns before introducing new abstractions.

## Testing Guidelines

There is currently no dedicated test framework or `npm test` script. For changes, run `npm run build` at minimum; use `npm run lint` when dependencies are available. For database or reservation changes, manually exercise the relevant public wishlist and admin flows, including quantity limits, claim/unclaim behavior, and guest-token access.

## Commit & Pull Request Guidelines

Recent history mostly uses Conventional Commit prefixes, such as `feat:`, `fix:`, `docs:`, and `chore:`. Use concise imperative messages, for example `fix: hide disabled reservation action`. Pull requests should include a short summary, verification steps, linked issue if applicable, and screenshots for UI changes. Note any database snapshot or migration changes explicitly.

## Security & Configuration Tips

Do not commit real admin tokens or secrets. Admin access is controlled by `ADMIN_TOKEN`; production deployment also depends on Traefik labels and the external `web` Docker network. Treat `data/db/wishlist.db` as a snapshot and checkpoint SQLite before committing database updates.