Imported from ak-softwares/wa-api (AGENTS.md). Install upstream with npx skills add ak-softwares/wa-api. Copyright stays with the author.

AGENTS.md

WhatsApp Business API SaaS (wa-api.me). Next.js 16 App Router, React 19, MongoDB/Mongoose, NextAuth JWT, Tailwind 4 + shadcn/Radix.

There is no Prisma. Path alias is @/ → src/. The folder src/utiles/ is an existing misspelling — use it; do not rename.

Run

npm run dev    # turbopack
npm run build
npm run lint

Env lives in .env.local (local) and .env.production (deploy). Never commit secrets.

Source layout

src/
  app/
    (app)/                 # public site + user dashboard (root layout with html/body)
      (public)/            # landing, auth, docs, pricing, legal
      dashboard/           # authenticated app
    (admin)/               # separate root layout; /admin
    api/                   # REST route handlers
  components/
    admin/                 # admin UI
    dashboard/             # user dashboard UI
    global/                # marketing header/footer
    ui/                    # shadcn primitives
    common/ emails/ providers/
  models/                  # Mongoose schemas
  services/                # business logic (WhatsApp, AI, webhooks, billing)
  hooks/                   # client data hooks
  lib/                     # db, auth helpers, redis, queues, crypto
  types/ schemas/ store/ config/ context/ utiles/

App routes

(app) and (admin) are two root layouts. Do not share html/body between them.

API groups (src/app/api/)

• auth/ — NextAuth, OTP, signup, password reset, temp setup tokens
• wa-accounts/ — chats, messages, contacts, templates, media, broadcast, analytics
• facebook/ — WABA onboarding
• subscription/ + razorpay/ — plans and Razorpay subscriptions (create-subscription, not one-off orders)
• admin/ — gated by requireAdminApi(). admin/stats is the all-time snapshot; admin/analytics?range= returns date-bucketed series plus growth rates
• ai/, tools/, api-token/, oauth/, users/me, webhooks/

API JSON shape: { success, message, data?, pagination? } (src/types/apiResponse.ts).

Data (MongoDB)

Models in src/models/: User, WaAccount, Chat, Message, Contact, Template, Subscription, SubscriptionUses, PaymentHistory, MonthlyUsage, AIAssistant, AiUsage, Tool, ApiToken, PushDevice.

Auth

• NextAuth JWT: src/app/api/auth/[...nextauth]/authOptions.ts
• Session: id, email, role
• User: role (user | admin), status (active | suspended)
• Admins: ADMIN_EMAILS (comma-separated) only. Bootstrap on login via src/lib/auth/resolveAuthUser.ts. The admin panel cannot grant or revoke role — PATCH /api/admin/users/[id] accepts status only
• Pages: requireAdminPage() in (admin)/layout.tsx (redirect)
• APIs: requireAdminApi() in src/lib/auth/requireAdmin.ts
• Most user APIs: fetchAuthenticatedUser() in src/services/apiHelper/getDefaultWaAccount.ts (Bearer JWT, API token, NextAuth session, or setup temp token)
• Suspended users cannot sign in

Building a feature

Create layers in this order. Do not skip to the page.

1. Model — Mongoose schema in src/models/.
2. Types — client-safe TypeScript types in src/types/ (no Mongoose). Mirror them in API responses.
3. API — thin src/app/api/.../route.ts. Auth with fetchAuthenticatedUser() or requireAdminApi(). Return ApiResponse.
4. Hook — src/hooks/... fetches the API, holds loading / data / errors, toasts via showToast.
5. Page / component — src/components/... plus a thin src/app/.../page.tsx. Pages stay presentational.

Loading

While data is loading, show skeletons (Skeleton from @/components/ui/skeleton), not a blank screen or a spinner-only page. Match the layout of the loaded UI (cards, table rows, list items). See MetricCardSkeleton, StatCard, admin tables.

Charts

Charts use recharts. Wrap every chart in ChartFrame (src/components/admin/charts/), which handles the card, skeleton, and empty state. Colors and axis defaults live in chartConfig.ts.

Date ranges on admin screens go through AdminRangeFilter + useAdminAnalytics, default preset lifetime. Range parsing and bucketing (daily up to 100 days, monthly beyond) live in src/lib/admin/analytics.ts.

Money

price on Subscription and PaymentHistory is stored in the smallest currency unit (paise/cents), as Razorpay returns it. Render it with formatMinorMoney(); formatMoney() expects major units.

Pagination

If a list can grow (users, chats, contacts, payments, etc.), paginate it. Do not dump unbounded arrays to the client.

• API: page, perPage (cap, typically 20–100). Return pagination: { page, perPage, total, totalPages } on ApiResponse.
• Admin helpers: parsePagination() in src/lib/admin/query.ts. UI: AdminPagination.
• Dashboard lists: ITEMS_PER_PAGE from src/utiles/constans/apiConstans.ts; hooks often use page + hasMore (load more).
• Facebook-style APIs may use cursor pagination (pagination.cursors / next) instead.

Conventions

• Keep business logic in services/; route handlers stay thin.
• Plan quotas are per month (messagesPerMonth). A yearly subscription's billing period is split into monthly usage windows by resolveUsagePeriod() in src/services/subscription/usageService.ts — never use subscription.currentStart/currentEnd directly as the quota window.
• Dashboard UI in src/components/dashboard/; admin UI in src/components/admin/.
• Client toasts: showToast from @/components/ui/sonner.
• Do not import Mongoose models into "use client" files.
• Encrypted WaAccount fields (permanent_token, business_id) must never be returned to admin or client UIs.
• Razorpay subscription webhooks: /api/webhooks/razorpay-subscription. /api/webhooks/razorpay is a signature-only stub (old wallet payments).
• Prefer existing patterns (hooks + fetch to /api/...) over new frameworks.

Stack notes

MongoDB, Redis, BullMQ, Pusher, Razorpay, Resend, OpenAI / Vercel AI SDK, Meta Cloud API. UI: Tailwind, DaisyUI leftovers, Radix/shadcn, Framer Motion, Zustand.