AlexandrAI AGENTS.md
agents-md

nk304 Web Next Agent Guide

Project-specific AGENTS.md guidance for the nk304 Next.js App Router frontend, shared UI primitives, Tailwind token discipline, sockets, i18n, and verification gates.

AGENTS.md

Guidance for coding agents working on nk304 apps/web-next. The root monorepo guide owns cross-cutting policy; this file focuses on the Next.js frontend boundary.

Project Overview

apps/web-next is the Next.js App Router surface for nk304. It uses React 19, Next.js 16, Tailwind v4, Radix primitives, Zustand stores, Socket.IO clients, i18next, rich document/media components, and domain-specific Open Chat and inventory workspaces.

The app is not a thin marketing site. It carries authenticated layouts, admin tabs, public checkout/order-form pages, Open Chat rooms, assistant panels, inventory/apartment/project workspaces, profile/settings routes, and a large component test surface. Treat it as the browser contract for the FastAPI API and the shared WebSocket constants.

Project Map

  • app/ holds App Router routes, layouts, auth pages, admin, Open Chat, checkout, invite, and account flows.
  • app/globals.css is the Tailwind v4 token and semantic utility source for frontend styling work.
  • src/components/ui/ contains shared primitives such as buttons, cards, dialogs, tables, labels, toast, markdown, avatars, and status badges.
  • src/components/layouts/ contains reusable authenticated and unauthenticated shells.
  • src/components/open-chat/ contains chat rooms, assistant panels, files, calendar, mentions, tickets, apartment, inventory, project, checkout, and message-input features.
  • src/components/admin/ contains operator tabs for users, rooms, data, files, reports, support tickets, notices, audit, logs, status, and settings.
  • src/lib/ contains API helpers, locale loading, presence, and focused domain utilities.
  • src/services/ is the main service boundary for API calls; prefer existing domain service folders instead of ad hoc fetches.

Setup Commands

Use repo-relative commands from the monorepo root:

bashpnpm --filter @nk304/web-next run dev
pnpm --filter @nk304/web-next run lint
pnpm --filter @nk304/web-next run typecheck
pnpm --filter @nk304/web-next run build
pnpm --filter @nk304/web-next run verify:theme
pnpm verify:web-next:contract
pnpm verify:web-next:no-legacy

For targeted tests, prefer the native Node runner against the specific .test.mts or .test.mjs file near the code you changed:

bashpnpm --filter @nk304/web-next exec node --test src/components/open-chat/<target>.test.mts

If a command requires local service ports, set environment variables locally and keep them out of committed docs and public reports.

Change Rules For Agents

  • Route new browser API calls through the existing API client or domain service folder unless the task is specifically about infrastructure.
  • Keep API payloads aligned with the generated contract and the /api/v2 envelope conventions from the root guide.
  • Reuse src/components/ui/ and existing Open Chat/admin shells before adding a new visual pattern.
  • Use semantic utilities and aliases from app/globals.css; avoid one-off color literals or local token forks.
  • For small icon actions, prefer icon-only controls with accessible labels and tooltip text where the existing pattern supports it.
  • Add English locale keys first when normal feature work introduces user-facing text. Propagate other locales only when requested or during a localization pass.
  • Do not bypass transport crypto or protected download flows with direct raw payloads, direct protected URLs, or query-string shortcuts.

Verification

Run the smallest useful check first, then broaden:

  • Component or utility change: nearest node --test file.
  • UI primitive/theme change: pnpm --filter @nk304/web-next run verify:theme.
  • API payload or endpoint change: pnpm verify:web-next:contract.
  • Route migration/import boundary change: pnpm verify:web-next:no-legacy.
  • Broad browser change: pnpm --filter @nk304/web-next run lint and pnpm --filter @nk304/web-next run typecheck.

Security Notes

Keep auth, CSRF, request id, origin-domain, and transport crypto headers flowing through the established client layers. Never paste real session values, service origins, upload links, Cloudflare details, or environment file contents into tests, fixtures, comments, logs, or public archive material.

PR Checklist

  • The changed route or component uses existing layout, shell, and token conventions.
  • API and socket constants are generated or imported rather than duplicated.
  • Locale changes preserve English fallback behavior.
  • Targeted tests cover the changed behavior.
  • Any protected file, payment, admin, or assistant path has a focused security or regression test.