# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

@AGENTS.md

## Commands

```bash
pnpm dev        # start dev server
pnpm build      # production build
pnpm lint       # ESLint
```

Copy `.env.example` to `.env.local` and set `API_BASE_URL` before running locally.

## Architecture

**Stack:** Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS v4 · shadcn/ui · TanStack Query v5 · next-intl · react-hook-form + Zod

**Routing:** All pages live under `app/[locale]/`. The locale segment is followed by route groups:
- `(auth)` — unauthenticated pages (login, forgot/reset password, account)
- `(dashboard)/(main)` — core super-admin resources (tenants, roles, agents, themes, …)
- `(dashboard)/(merchant)` — merchant-scoped resources (plans, FAQs, CMS templates, tickets)
- `(dashboard)/(markatty)` — markatty-brand resources (sliders, testimonials, partners, videos, analytics scripts)
- `(dashboard)/(settings)` — system settings (currencies, locales, exchange rates, channels)

**BFF proxy:** The browser never talks to the upstream API directly. All API traffic goes through `app/api/super/[...path]/route.ts`, which reads the `super_admin_token` httpOnly cookie and forwards requests to `API_BASE_URL`. Auth is handled at `app/api/auth/login|logout/route.ts`.

**Data fetching pattern:** All data fetching is client-side via TanStack Query hooks (`hooks/api/use-*.ts`). Pages are thin server components that render a client component; the client component fetches its own data using the appropriate hook. Mutations use `apiRequest` from `lib/api/client.ts`.

**API layer layout:**
- `lib/api/*.ts` — client-side fetchers and mutation helpers
- `lib/api/schemas/` — Zod schemas that map response shapes
- `hooks/api/use-*.ts` — TanStack Query hooks (one per resource)
- `lib/api/query-keys.ts` — shared query key factory

**i18n:** `next-intl` with `messages/en.json` and `messages/ar.json`. Feature-specific copy lives under a namespace matching the feature (e.g. `Sliders`, `Agents`). Shared copy is under `Common`.

**ACL / permissions:** `lib/acl-routes.ts` defines every resource, its nav entry, and the permission keys required for list/view/create/edit. `lib/auth/permissions.ts` exposes `canAccessRoute`, `canSeeNavGroup`, and `hasPermission` for guard logic in layouts and nav components.

**Delete confirmation rule:** Any delete or permanent-remove action **must** show a localized confirmation before calling the API. Use `window.confirm(t("confirm.delete", { name }))` in table handlers, or use the `EditDangerSection` component (which handles confirmation internally). See `.cursor/rules/delete-confirmation.mdc` for full guidance.

**Component conventions:**
- `components/ui/` — unstyled shadcn/ui primitives (do not modify directly; re-run `shadcn add` to update)
- `components/` — composed feature components (editors, tables, views)
- `SuperDataTable` / `DataTable` — shared paginated table with column header sorting and toolbar
- `EditDangerSection` — danger zone for edit pages (handles delete confirmation)
**API contract:** `Super Admin API.postman_collection.json` at the repo root is the authoritative API reference. Update Zod schemas in `lib/api/` when response shapes change.