Repository Guidelines

Project Structure & Modules

Docs live in docs/; start with project-overview.md, phases-plan.md, then frontend/ and backend/. README.md summarizes; DOCS.md indexes English docs.
Agent configs sit in agents/; core rules are in RULES.md. Use the feature-first layout from docs/frontend/architecture.md (app/, features/, entities/, shared/) mapped to invoicing, expenses, payroll, compliance.

Frontend: Next.js (TypeScript, App Router), Tailwind CSS, React Query/SWR. Backend: Node.js + TypeScript with Express/Fastify; BullMQ (Redis); Prisma or Drizzle.
Data: Postgres (Supabase/RDS) + pgvector; include EventLog.source_agent (default balance) and Transaction.reasoning_trace JSONB for explainability.
Ops: Dockerized deploys (Render/Fly.io/Railway). Payments: Stripe. Auth: Clerk/Auth.js. LLM: OpenAI API via one helper; model switches must be one-line.

Do not run npm run dev (repository rule). Use npm run build to verify compilation; rerun after meaningful changes.
Add npm test / npm run lint when tooling is added; document scripts in README.md and here. Docs-only changes: just check links.

Prefer Server Components; mark client components explicitly. Keep code feature-first; put shared utilities in shared/ and API clients in dedicated modules. Encapsulate finance/LLM integrations behind services.
Names in English; use descriptive files. Follow framework defaults; run Prettier/ESLint if configs exist. Keep prompt logic only in the LLM helper.

Layered coverage: unit tests for calculations/rules; component tests for invoicing, expense upload, reconciliation; E2E for onboarding, ingestion, categorization, approval, payment.
Name tests *.spec.ts / *.test.ts(x) alongside code or under __tests__/. Mock Stripe, tax/reporting APIs, QuickBooks webhooks, and LLM calls. Validate webhook handling and reasoning_trace persistence via backend-facing mocks.
Document test commands and required env vars in README.md.

Use concise, imperative commit messages. PRs: state purpose/scope, affected modules/docs, validation (npm run build, tests), screenshots if UI. Link tasks/issues; note risks (provider edges, missing secrets, migrations). Update docs when behavior or decisions change.

Review RULES.md and relevant agent files before coding. Keep secrets out of the repo; use env vars and never commit provider keys, bank tokens, or webhook secrets.
All LLM calls must pass through the shared helper to centralize config and logging.
Maintain APIs for transactions, approvals, overrides, reports, rules, billing; expose read-only /api/events for downstream agents. Log TX_INGESTED, TX_CATEGORIZED, TX_APPROVED, RULE_CREATED, REPORT_GENERATED with source_agent; persist reasoning_trace for auditability.
Keep project phase/status aligned across README.md, DOCS.md, and docs/phases-plan.md; update when phase changes.