Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (45 loc) · 2.74 KB

AGENTS.md

File metadata and controls

58 lines (45 loc) · 2.74 KB
Raw

AGENTS.md

What this repo is

JupiterAPI is an Express read-API over ESN Jupiter (upstream SaaS) that normalizes users, events, and section data for dashboards and exports. It also exposes an optional JWT-gated write proxy (/hercules/*) that records board-managed data (events, fidelity, attendance, approvals) in Firestore.

Layout

Path Ownership
src/index.js Bootstrap only: middleware chain + route mounting. Zero business logic.
src/routes/ ALL HTTP routers — one file per URL prefix (users.js, events.js, stats.js, auth.js, hercules.js, ...).
src/middleware/ Cross-cutting concerns: apiKeyAuth, rateLimiter, jwtAuth, validation, asyncHandler.
src/jupiter.js Sole upstream Jupiter client (Cognito auth, interceptors, 5-min cache).
src/config.js Sole reader of process.env; fail-fast validation at require time.
src/nationality.js, src/fieldsOfStudy.js, src/eventLocation.js, src/formatting.js, src/normalizers.js Pure domain logic. Never import express or jupiter.js.
src/googleContacts.js Google Contacts CSV row building + streaming.
test/unit/ Characterization tests for pure modules.
test/routes/ HTTP suites with mocked Jupiter/Cognito/Firestore.
docs/ openapi.yaml (API reference), ARCHITECTURE.md, FEATURES.md.

Architectural rules (must-not-violate)

  • Routers own HTTP only; business logic lives in domain modules or jupiter.js.
  • No business logic in index.js.
  • Only jupiter.js calls the upstream API.
  • Only routes/hercules.js writes Firestore.
  • Environment variables are read only in config.js.
  • Board-member authorization uses immutable Cognito sub IDs only (config.boardMemberIds) — never usernames.
  • Domain modules stay express-free and jupiter-free.
  • Keep docs/openapi.yaml and README.md in sync with any endpoint change.

Where changes belong

  • New endpoint → src/routes/<domain>.js + a row in docs/FEATURES.md + docs/openapi.yaml + README API overview.
  • New env var → src/config.js (+ .env.example). Nowhere else.
  • Upstream payload quirk ("null" strings, 400-means-404) → jupiter.js interceptors or normalizers.js.
  • Stats math → routes/stats.js.
  • City inference rules → eventLocation.js / fieldsOfStudy.js.
  • Nationality/country mapping → nationality.js.

Commands

npm start        # run server
npm run dev      # run with NODE_ENV=development
npm test         # node --test over test/**/*.test.js
npm run lint     # eslint .

No build step or typecheck — plain CommonJS JavaScript.

Read before modifying

  1. This file (AGENTS.md)
  2. docs/ARCHITECTURE.md
  3. The feature's row in docs/FEATURES.md
  4. The owning module