cim_summary/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

Two runnable apps sit alongside documentation in the repo root. backend/src holds the Express API with config, routes, services, models, middleware, and __tests__, while automation lives under backend/src/scripts and backend/scripts. frontend/src is the Vite + React client organized by components, contexts, services, types, and Tailwind assets. Update the matching guide (DEPLOYMENT_GUIDE.md, TESTING_STRATEGY_DOCUMENTATION.md, etc.) when you alter that area.

Build, Test, and Development Commands

• cd backend && npm run dev – ts-node-dev server (port 5001) with live reload.
• cd backend && npm run build – TypeScript compile plus Puppeteer config copy for deployments.
• cd backend && npm run test|test:watch|test:coverage – Vitest suites in src/__tests__.
• cd backend && npm run test:postgres then npm run test:job <docId> – verify Supabase/PostgreSQL plumbing per QUICK_START.md.
• cd frontend && npm run dev (port 5173) or npm run build && npm run preview for release smoke tests.

Coding Style & Naming Conventions

Use TypeScript everywhere, ES modules, and 2-space indentation. ESLint (backend/.eslintrc.js plus Vite defaults) enforces @typescript-eslint/no-unused-vars, warns on any, and blocks undefined globals; run npm run lint before pushing. React components stay PascalCase, functions/utilities camelCase, env vars SCREAMING_SNAKE_CASE, and DTOs belong in backend/src/types.

Testing Guidelines

Backend unit and service tests reside in backend/src/__tests__ (Vitest). Cover any change to ingestion, job orchestration, or financial parsing—assert both success/failure paths and lean on fixtures for large CIM payloads. Integration confidence comes from the scripted probes (npm run test:postgres, npm run test:pipeline, npm run check:pipeline). Frontend work currently depends on manual verification; for UX-critical updates, either add Vitest + Testing Library suites under frontend/src/__tests__ or attach before/after screenshots.

Commit & Pull Request Guidelines

Branch off main, keep commits focused, and use imperative subjects similar to Fix EBITDA margin auto-correction. Each PR must state motivation, summarize code changes, link tickets, and attach test or script output plus UI screenshots for visual tweaks. Highlight migrations or env updates, flag auth/storage changes for security review, and wait for at least one approval before merging.

Security & Configuration Notes

Mirror .env.example locally but store production secrets via Firebase Functions secrets or Supabase settings—never commit credentials. Keep DATABASE_URL, SUPABASE_*, Google Cloud, and AI provider keys current before running pipeline scripts, and rotate service accounts if logs leave the network. Use correlation IDs from backend/src/middleware/errorHandler.ts for troubleshooting instead of logging raw payloads.