Paddy
17ca6399e0
New /feedback API domain backed by its own FEEDBACK_DB, mirroring the Calendar domain's router -> service -> DB pool layering: - Public endpoints (no auth): eligible-events listing, event config, submission with honeypot + rate limiting (in-memory + DB backstop). - Admin endpoints (session-header auth, reusing Calendar's users/sessions via a swappable feedback.auth.ts boundary): events/songs/questions CRUD, bulk reorder/assignment, aggregated reporting, CSV export. - Schema in sql/feedback/001_init.sql (8 tables), applied and verified against the real FEEDBACK_DB. - 64 Jest tests covering validation, auth, rate limiting, CSV escaping, and report aggregation (pure functions, no DB needed). Includes fixes from a security review: path traversal defense doesn't apply here (that's the frontend proxy, separate repo), but the rate-limiter cluster does - recordSubmission now counts every processed request (not just successful ones), the in-memory Map evicts empty entries instead of growing unbounded, FEEDBACK_IP_SALT is required at boot instead of silently degrading to unsalted hashing, and submission answer/rating arrays are capped and de-duplicated to bound insert amplification. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2.8 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Commands
npm run build # Compile TypeScript → dist/
npm run start # Build and start (tsc && node ./dist/app.js)
npm run debug # Start with DEBUG=* environment variable
npm run test # Run Jest tests with coverage (outputs sonar-report.xml)
Run a single test file:
npx jest test/some.test.ts
Architecture
Express.js REST API in TypeScript with a service-oriented layering. Domains: Calendar (events, users) and Feedback (concert feedback forms, mounted at /feedback, backed by its own FEEDBACK_DB — see src/models/feedback/, still scaffolding-only as of this writing).
Request path:
app.tsmountsCalendar.router.tsat/calendarCalendar.router.tsdelegates toevents.router.tsandusers.router.ts- Routers call services; services call the MariaDB pool in
Calendar.db.ts
Key layers:
| Layer | Location |
|---|---|
| Router | src/models/calendar/Calendar.router.ts, …/events/events.router.ts, …/users/users.router.ts |
| Services | …/events/events.service.ts, …/users/users.service.ts, …/events/credentials.service.ts, …/events/icalgenerator.service.ts |
| DB pool | src/models/calendar/Calendar.db.ts (MariaDB, pool size 5) |
| Shared | src/common/ (base route class, nodemailer wrapper), src/middleware/logger.ts (Winston) |
Auth model: Users must have a @nachklang.art email. After activation they receive a session token (30-day window); the token hash + IP are stored in the DB. Credentials for non-user calendar access (MEMBER_CREDENTIAL, CHOIR_CREDENTIAL, MANAGEMENT_CREDENTIAL) come from .env.
Event versioning: Events have a companion event_versions table. events.service.ts manages writes to both.
Calendar types and IDs: public (1), members (2), management (3), choir (4), birthdays (5). credentials.service.ts enforces which session/credential can read each calendar.
iCal export: icalgenerator.service.ts converts DB events to RFC 5545 format; reachable via GET /calendar/events/{calendar}/ical.
API docs: Swagger UI served at /docs, generated from JSDoc annotations in the router files.
Environment
Copy .env.example (or create .env) with:
PORT=
DB_HOST=
DB_USER=
DB_PASSWORD=
CALENDAR_DB=
FEEDBACK_DB=
FEEDBACK_IP_SALT=
FEEDBACK_RATE_LIMIT_MAX=
FEEDBACK_RATE_LIMIT_WINDOW_MIN=
SALESFORCE_ENABLED=
SALESFORCE_API_URL=
SALESFORCE_API_TOKEN=
EMAIL_HOST=
EMAIL_USERNAME=
EMAIL_PASSWORD=
MEMBER_CREDENTIAL=
CHOIR_CREDENTIAL=
MANAGEMENT_CREDENTIAL=
TypeScript config
Strict mode enabled, target ES2016, compiled output in ./dist, inline source maps. Tests run through ts-jest directly against .ts sources.