AlexandrAI AGENTS.md
agents-md

AB Server Agent Guide

Project-specific AGENTS.md guidance for the AB Node API server, domain modules, migrations, media refs, Docker infra, and verification commands.

AGENTS.md

Guidance for coding agents working on AB Server. Humans read README.md; this file keeps the operational rules an agent needs before editing the Node API repo.

Project overview

ab-server is the Node.js API server for the AB mobile A/B-vote product. The client and operator console live in sibling repositories, and this service communicates with them only over HTTP contracts. The runtime combines a Node API, PostgreSQL, Redis, and S3-compatible media storage behind Docker Compose.

Media bytes do not belong in the database. Store and pass opaque media references, then resolve them to public or signed URLs at the API boundary.

Setup commands

bashcd <project-root>/ab-server
npm install
npm run dev

For local infrastructure, copy the example environment file to a local env file and start the compose stack. Keep the copied file private and never paste real values into docs or commits.

bashcd <project-root>/ab-server
cp .env.docker.example <LOCAL_ENV_FILE>
npm run docker:infra:up
npm run seed:dev

Code organization

  • Domain logic belongs in server/domain/.mjs, then gets re-exported through the server/domain.mjs barrel.
  • Route handlers belong in server/routes/*.mjs; shared request helpers belong in server/http/.
  • server/api-server.mjs stays bootstrap and dispatch only. Do not put route bodies there.
  • Schema changes require server/storage.mjs, a new database/migrations/00N_*.sql, and a regenerated bootstrap SQL check.
  • Source files under server/, scripts/, tests/, and public/ must stay at or below the project size threshold enforced by npm run lint:size.

Testing and verification

bashnpm run lint:size
npm run db:bootstrap:check
npm test
npm run verify

npm run verify includes size checks, database bootstrap validation, unit tests, API smoke checks, frontend smoke checks, evidence smoke checks, local preprod smoke, and sponsored workflow smoke checks. Smoke commands require the local infrastructure stack to be running.

Security and data handling

Do not publish, commit, or log copied environment values. Use placeholders such as <DB_HOST>, <PORT>, <AB_ADMIN_TOKEN>, and <S3_SECRET> in public notes. Use container-local database tooling for ad hoc inspection instead of installing host tools during agent work.

Keep presigned media flow intact: sign upload, let the client upload bytes, store only the media reference, and resolve it at the server boundary.

Commit and PR rules

Keep changes surgical, add focused tests for new domain modules or routes, and run the narrow command first before npm run verify. If a migration changes behavior, include both the SQL migration and the bootstrap export check result in the PR summary.