AGENTS.md

Guidance for coding agents working on Local Link Kr Server, the Node ESM API server for the Local Link Kr suite.

Project Overview

The server is a reusable API scaffold with PostgreSQL-only persistence, plain SQL migrations, focused Node test files, and email-verified signup. Sibling web, admin, and mobile clients communicate over HTTP; they must not import runtime server source.

Key paths:

server/api-server.mjs: bootstrap and dispatch only.
server/domain.mjs and server/domain/: domain logic.
server/routes/: HTTP route modules.
server/http/: parsing and response helpers.
database/migrations/00N_*.sql: ordered schema changes.
scripts/dev-server.mjs, scripts/migrate.mjs, scripts/check-file-size.mjs: runtime and guard scripts.
tests/*.test.mjs: Node test suites for auth, schema, routes, security, and domain behavior.

Setup Commands

bashcd <project-root>/server
npm install
npm run dev
npm run db:migrate
npm test
npm run verify

Docker suite startup is owned by the deploy sibling:

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

Use placeholder environment values such as DATABASE_URL=<POSTGRES_URL> and SMTP_PASSWORD=<SMTP_PASSWORD> in docs and examples.

Code Style

Keep server/api-server.mjs thin; do not grow route logic in the bootstrap file.
Add a new numbered migration for each schema change. Keep migrations idempotent where possible.
Keep domain logic testable outside HTTP routing.
Put request parsing, validation, and response helpers in the HTTP layer rather than duplicating route boilerplate.
Add focused tests for each new domain, route, storage, or migration behavior.

Public signup goes through request-code and verify-code endpoints.
Do not expose a direct /api/users creation path.
Password login must support email/password for verified users.
Passwords use scrypt hash and salt.
Session tokens and verification codes are stored only as hashes.
Verification codes must expire and be single-use.

Security

Load database, SMTP, verification, and session secrets from runtime environment only.
Never commit or print SMTP credentials, session tokens, password hashes, or verification codes.
Keep admin-only behavior out of the public API surface unless explicitly routed through authenticated checks.
If logging request failures, redact auth headers, cookies, and secret-bearing payload fields.

Done Criteria

npm run verify passes.
Schema changes have migrations and tests.
Auth changes prove both allowed and rejected paths.
Public documentation uses placeholders, not private endpoints or machine-specific paths.

Local Link Kr Server Agent Guide