AlexandrAI AGENTS.md
agents-md

Local Link Kr Web Agent Guide

Project-specific AGENTS.md guidance for the Local Link Kr public Next.js web app, API client boundary, page/component split, and verification workflow.

AGENTS.md

Guidance for coding agents working on Local Link Kr Web, the public Next.js app in the Local Link Kr suite.

Project Overview

The web app is the public surface. It communicates with the server over HTTP through a centralized client and must not import server, admin, or mobile runtime source.

Key paths:

  • src/lib/api-client.mjs: the API access boundary.
  • src/components/: reusable UI components.
  • src/app/: Next.js pages and route-level composition.
  • tests/*.test.mjs: Node tests for API-client and Local Link client behavior.
  • Dockerfile and next.config.mjs: deployment/runtime surface.

Setup Commands

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

Run the full suite through deploy when checking web-to-server integration:

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

Use <SERVER_URL> or a documented runtime variable in examples. Do not publish private local URLs or ports.

Code Style

  • Pages stay thin; move reusable UI into src/components.
  • All outbound API calls go through src/lib/api-client.mjs.
  • Keep public web behavior separate from admin-only behavior.
  • Prefer typed, narrow data shapes for API responses; do not let route components depend on raw response blobs.
  • Keep error states visible and user-safe without exposing backend internals.

Testing

  • Run npm run verify before calling web work done.
  • Add tests for API-client behavior when changing request construction, error mapping, timeouts, or response parsing.
  • Use npm run typecheck for component and route changes even if the change looks visual.
  • Build before shipping changes to routing, server components, or Next configuration.

Security

  • Public pages must not include admin-only controls, hidden admin calls, or privileged data.
  • Browser code must not contain server secrets or credentials.
  • Treat server errors as untrusted input; render safe user-facing messages.
  • Do not embed internal endpoints, local ports, or deployment-only hostnames in committed docs or test fixtures.

Commit And PR Rules

  • State whether the change is UI-only, API-client, routing, or deployment-related.
  • Include the verification command run.
  • When a web change depends on server behavior, link the server-side route or contract expectation in the PR summary.