Skip to content

CLAUDE.md

Latest commit

 

History

History
74 lines (58 loc) · 2.4 KB

CLAUDE.md

File metadata and controls

74 lines (58 loc) · 2.4 KB

Developer Notes

This repository contains a Node.js/Express API service for ESN Jupiter data and optional Hercules write workflows.

Run locally

npm install
cp .env.example .env
npm start

Default URL: http://localhost:3002

Project layout

src/
  index.js              App bootstrap, middleware chain, route mounting
  jupiter.js            Jupiter API client, Cognito auth, request caching
  utils.js              Data normalization and helper logic
  auth.js               Cognito login/refresh/verify/logout routes
  hercules.js           Firestore write proxy endpoints (optional)
  googleContacts.js     CSV export helpers
  middleware/
    apiKeyAuth.js       X-Api-Key header authentication
    rateLimiter.js      In-memory rate limiter with cleanup
    jwtAuth.js          JWT verification + board-member gate
    validation.js       Request validation helpers
  routes/
    system.js           GET /health, /metrics
    users.js            GET /users, /users/search, /users/:id
    events.js           GET /events, /events/archived, /events/:id, subscriptions
    section.js          GET /section
    nationalEvents.js   GET /national-events
    requests.js         GET /requests
    treasury.js         GET /treasury/cash-flow
    stats.js            GET /stats/* (nationality, field-of-study, overview, cities, comprehensive)
    export.js           GET /export/google-contacts
docs/
  openapi.yaml          Public API reference (OpenAPI 3.0)

Security model

  • Read endpoints use X-Api-Key authentication in production.
  • /auth/* routes are public and handle Cognito token flows.
  • /hercules/* routes require Cognito JWT and board-member authorization.
  • Board membership must be configured with immutable Cognito sub IDs (BOARD_MEMBER_IDS).

Configuration

All runtime configuration is environment-driven. See .env.example for the canonical template.

Core variables:

  • AWS_COGNITO_REGION
  • AWS_COGNITO_USER_POOL_ID
  • AWS_COGNITO_CLIENT_ID
  • COGNITO_USERNAME
  • COGNITO_PASSWORD
  • JUPITER_API_BASE_URL

Optional advanced variables:

  • BOARD_MEMBER_IDS
  • GOOGLE_APPLICATION_CREDENTIALS

Contributor guidance

  • Keep API behavior documented in both README.md and docs/openapi.yaml.
  • Do not commit credentials, .env, or service account JSON files.
  • Prefer immutable IDs (sub) for authorization logic.
  • Keep changes focused and avoid broad refactors without tests.