AlexandrAI AGENTS.md
agents-md

Local Link Kr Admin Agent Guide

Project-specific AGENTS.md guidance for the Local Link Kr network-gated Next.js admin console, BFF routes, session cookies, and security invariants.

AGENTS.md

Guidance for coding agents working on Local Link Kr Admin, the network-gated operator console.

Project Overview

The admin app is a Next.js App Router console behind a custom server gate. Browser code calls local BFF routes first; BFF routes call the backend API through one upstream client. The backend must not be called directly from browser components.

Request flow:

textbrowser -> src/app/api/**/route.ts -> src/lib/api-client.mjs -> local-link-kr-server

Key paths:

  • server.mjs: network gate and production app server.
  • src/app/api/**/route.ts: BFF route handlers.
  • src/lib/api-client.mjs: upstream API boundary and timeout behavior.
  • tests/admin-bff-auth.test.mjs, tests/network.test.mjs, tests/api-client.test.mjs: security and client checks.

Setup Commands

bashcd <project-root>/admin
npm install
npm run dev
npm test
npm run typecheck
npm run build
npm run verify

Use the deploy sibling for suite-level checks:

bashcd <project-root>/deploy
docker compose -f compose.development.yml up --build

Keep examples generic: use <ADMIN_ORIGIN>, <SERVER_URL>, and <SESSION_SECRET> placeholders.

Security Invariants

  • server.mjs enforces the admin network gate before app pages are served.
  • Trusted proxy headers are honored only when the socket peer is trusted.
  • Upstream admin/session credentials stay in httpOnly cookies.
  • BFF routes fail fast before upstream fan-out when credentials are absent.
  • Every upstream call goes through src/lib/api-client.mjs.
  • Admin UI must not downgrade auth failures into anonymous or public behavior.

Code Style

  • Keep server-gate logic centralized in server.mjs.
  • Keep route handlers small: validate credentials, call the API client, map response.
  • Keep operator UI reusable, but do not share runtime source with the public web app when it would mix privileged behavior.
  • Add tests whenever a credential, proxy, network, cookie, or upstream timeout rule changes.

Testing

  • Run npm run verify before calling admin work done.
  • Use tests/network.test.mjs for trusted-proxy or network-gate changes.
  • Use BFF auth tests for absent, expired, malformed, or rejected credential paths.
  • Build after changing Next routes, server configuration, or deployment behavior.

Commit And PR Rules

  • Name the affected security boundary in the PR summary.
  • Include the verify command and any focused test run.
  • Do not publish real admin URLs, session cookie values, proxy IPs, or credentials.