# 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.

## Core Stack & Services
- 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.

## Build, Test, and Development Commands
- **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.

## Coding Style & Naming
- 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.

## Testing Guidelines
- 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`.

## Commit & Pull Request Guidelines
- 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.

## Agent, API, & Security Notes
- 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.