# Repository Guidelines

This document summarizes how to work effectively in this repo.

## Project Structure & Module Organization
- `src/app`: Next.js App Router (Next 14). Localized routes under `src/app/[locale]`. Global styles in `src/app/globals.css`.
- `src/components`: Reusable UI in PascalCase (e.g., `Header.tsx`).
- `src/servers`: Server-side data and actions (DB, search, works APIs).
- `src/libs`: Integrations and utilities (Stripe, Replicate, R2, DB helpers).
- `src/configs`: App/third‑party config (e.g., `stripeConfig.ts`, `openaiConfig.ts`).
- `src/i18n`, `src/context`: Localization and React context.
- `public`: Static assets. `sql/tables`: PostgreSQL DDL.
- Path alias: import app modules via `~/*` (see `tsconfig.json`).

## Build, Test, and Development Commands
- `npm run dev` / `yarn dev`: Start local dev server on port 3000.
- `npm run build`: Production build (`.next`).
- `npm start`: Serve the built app.
- `npx next lint`: Run ESLint checks.

Environment: copy `.env.example` → `.env.local` and fill required keys (Stripe, Replicate webhook URL, Google OAuth, R2, Postgres). For first run, create tables from `sql/tables/*` in your database.

## Coding Style & Naming Conventions
- TypeScript, React, Next.js App Router.
- Indentation: 2 spaces; prefer explicit types for public APIs.
- Components: PascalCase (`MyComponent.tsx`). Hooks: `useX.ts`.
- Modules/utilities: camelCase (`helpers.ts`), server modules under `src/servers`.
- Imports: prefer `~/...` alias for internal paths.
- Linting: ESLint (`extends: next/core-web-vitals`); run `npx next lint --fix` before pushing.
- Styles: TailwindCSS in components; keep class lists readable and deduplicated.

## Testing Guidelines
- No formal test framework is configured yet. Perform manual QA for:
  - Auth flows, payment (Stripe test mode), image generation webhooks (use ngrok for local Replicate webhook), and locale pages.
- If adding automated tests, prefer Playwright for E2E and React Testing Library for components; place tests adjacent to sources.

## Commit & Pull Request Guidelines
- Commits: short, imperative subject (e.g., "fix r2 region", "add stripe config"). Group related changes.
- PRs: clear description, linked issue, steps to validate (commands, URLs), and screenshots for UI changes.
- Keep changes scoped; update README and configs when behavior or env vars change. Never commit secrets.

## Security & Configuration Tips
- Store secrets only in `.env.*`. Rotate keys used for local testing. Verify webhook and cron/automation settings if deploying to Vercel.