orbital-express AGENTS.md

AGENTS.md — Agent guide for Orbital-Express

Canonical, tool-agnostic instructions for any AI agent working in this repo (Claude Code reads it via CLAUDE.md; Cursor/Codex/Copilot read AGENTS.md directly). Keep this file concise — it points to the deep docs rather than duplicating them.

What this is

Orbital-Express is an opinionated Express.js + Sequelize (PostgreSQL) framework for building really good backend APIs. Feature-folder architecture (Django + Rails hybrid): everything for a feature — model, routes, controller, actions, tasks, tests, i18n, mailers — lives in one folder under app/. A background-job system (Bull/Redis) and Socket.IO layer sit alongside.

Where the knowledge lives (read these for depth)

• README.md — the full human onboarding doc. Deep explanations of every folder, pattern, and flow. Read the relevant section before non-trivial work.
• docs/conventions.txt — the terse, authoritative rulebook (naming, file structure, DB, auth, sockets, etc.). When a rule is ambiguous, this wins.
• database/schema.sql — documentation of every table (not executed). The column-order / naming template is at the top.
• docs/auth-migration.md — the access+refresh auth design and status.
• docs/google-oauth-setup.md — how to provision Google OAuth for "Sign in with Google".
• docs/workflow.md — the feature-development lifecycle (Path A new feature, Path B modify existing). The high-level map; the create-feature/modify-feature skills are the step-by-step.
• .claude/skills/ — step-by-step playbooks for common tasks (see "Skills" below). Prefer running these.

⚠️ Historical/outdated: docs/tests.txt predates the current setup (it mentions mocha). Ignore it — write-tests, the README, and conventions.txt are authoritative.

Golden rules (non-negotiable)

1. Plan and get sign-off before edits or scaffolding, for new and existing features. Then use the generator: yarn gen Feature, yarn gen Feature -a V1Action, yarn gen Feature -t V1Task, yarn gen Feature -m Mailer. Never hand-create feature files when scaffolding exists. Generator names/targets are validated before writes; existing source/test/mailer targets abort without writes; new source/test/templates are exclusive-created; indexes are deduplicated and sorted. Remove placeholder actions/tasks with yarn del (never rm), then run yarn repair Feature --dry-run before yarn repair Feature. 1b. Every app/<Feature> has the complete standard structure. There are no model-only/table-only exceptions. Extra domain files are allowed. Repair creates only missing files from generator templates, never overwrites existing files, restores missing action/task tests, creates README markers for otherwise-empty standard directories, and reports ambiguous route/controller/worker wiring instead of inventing policy.
2. Install exact versions only: yarn add <pkg> --exact (and --dev for dev deps). Never ^/~.
3. JS file structure (every .js file): header comment → 'use strict' → env → built-ins → third-party → services → helpers → models → queues (queue.get('XQueue') instances, right after models; the queue service is required up in services) → module-level consts → module.exports (before the methods) → method definitions. Imports ordered by increasing length, plain requires before destructured. Close every function with // END <name>. (README: "JavaScript File Structure".)
4. Naming: actions V{version}{Action}[By{Role}][On{Device}]; tasks append Task; feature folders singular PascalCase; controllers plural, actions singular; constants UPPER_CASE; booleans start with is/has/can/does; FK columns <entity>Id → PascalCase plural table. 4b. No magic strings. Any string literal used — or likely to be used — in more than one place (statuses, types, roles, locales, enum-like values) lives once in helpers/constants.js and is referenced, e.g. LOCALE.EN not 'en'. Use the add-constant skill. (Migrations stay literal — frozen snapshots.)
5. HTTP: POST and GET only. Use req.args (never req.body/req.query). Responses are flat: { status, success: true, ...payload } — no data nesting. Status: 200 default, 201 on create, 202 on background-job handoff. Route URLs are lowercase, no separators, even multi-word (V1LogoutAll → /v1/users/logoutall, not logout_all/-all/camelCase).
6. Errors: HTTP actions return errorResponse(req, ERROR_CODES.X, ...); tasks & socket-invoked actions throw. Never return a 500 manually — let it propagate to middleware/error.js.
7. Models: UUID v7 PKs (defaultValue: () => uuidv7() — require { v7: uuidv7 } from 'uuid'; validate: { isUUID: 7 }); paranoid: true soft-deletes (use scope(null) to bypass); explicit static PascalCase plural tableName (including irregular plurals); always index FKs; carry the owner FK onto every descendant + protect with a composite FK; named indexes use that exact table name in {Table}_{col}_{idx|unique} in BOTH model and migration.
8. i18n: keys are NAMESPACE[snake_case]; edit feature languages/*.js, then run yarn lang (it compiles locales/ and validates keys — required, and yarn test runs it first).
9. Tests: every action and task has an active test; required counterparts cannot use describe/it/test.skip, xit, xtest, it.todo, or test.todo. Every ERROR_CODE in the JSDoc has a test; test who cannot do something; fixtures are baselines you mutate in-test; run with --runInBand. Test location mirrors source: actions → app/<Feature>/tests/integration/, tasks → app/<Feature>/tests/tasks/, global helpers/services → test/helpers/ or test/services/.
10. One user type = one table (Admin, User, …) — never a single table with a role column. Auth is access token + revocable refresh token; see the add-auth-user-type skill.
11. Docs travel together. The same conventions are documented in documentation.html, README.md, docs/conventions.txt, AGENTS.md, CLAUDE.md, database/schema.sql, and the .claude/skills/. Editing one is not done until you've reconciled the others that cover the same thing — including the relevant skill(s). Follow the sync-docs skill. (A PostToolUse hook reminds you on every doc edit.)
12. Convention enforcement is mandatory. Run yarn conventions:check and the review-conventions skill after every non-trivial change. Root routes, models, workers, and errors auto-discover complete feature folders; actions live in actions/.