AlexandrAI AGENTS.md
agents-md

AB Admin Agent Guide

Project-specific AGENTS.md guidance for the AB Next.js operator console, network gate, BFF request flow, design rules, and verification commands.

AGENTS.md

Guidance for coding agents working on AB Admin. This repo is an operators-only Next.js console, not a public web surface.

Project overview

ab-admin is a Next.js App Router and React operator console. The browser never calls the API server directly. Requests go through route handlers, then src/lib/ab-api.mjs, and then the upstream AB API. The upstream session id remains in an httpOnly cookie and must not be exposed to client JavaScript.

Setup commands

bashcd <project-root>/ab-admin
npm install
AB_API_BASE_URL=<AB_API_URL> npm run dev

The custom server reads PORT, HOST, AB_ADMIN_ALLOWED_NETWORKS, AB_ADMIN_TRUSTED_PROXIES, AB_ADMIN_UPSTREAM_TIMEOUT_MS, and AB_ADMIN_LIST_LIMIT. Use placeholders in public docs and keep real values in local deployment configuration.

Design rules

Read DESIGN.md before changing screens, panels, or components. Tokens live in src/app/globals.css; use existing CSS variables instead of hardcoded color or spacing values when a token exists. This is a dense operator console, so prioritize clarity, scanability, and predictable controls over decorative layout.

Code organization

  • server.mjs wraps Next.js and enforces the network gate. Keep new feature logic out of it.
  • src/components/AdminApp.tsx is already large. Split new tabs or panels into components and hooks instead of growing it.
  • App shell files live in src/app/.
  • Backend-backed actions belong in src/app/api/**/route.ts plus a matching function in src/lib/ab-api.mjs.
  • src/lib/ab-api.mjs is the only module that talks to the upstream API.
  • Session and auth helpers live in src/lib/session.ts.
  • Network allowlist logic lives in src/lib/network.mjs and is security-sensitive.

Testing and verification

bashnpm test
npm run typecheck
npm run build
npm run verify

Add focused tests for network gate changes, session behavior, upstream timeout behavior, and new BFF route handlers.

Security invariants

Preserve the network gate default posture. Honor forwarded headers only through trusted proxies. Always call requireAdminCredentials before upstream fan-out. Keep all upstream calls on abFetch so timeouts and cancellation behavior remain consistent.

Commit and PR rules

For UI changes, cite DESIGN.md constraints and include the verification commands. For security-sensitive changes, include the exact invariant preserved and the focused tests added.