3.5 KiB
Repository Guidelines
Project Structure & Responsibilities
Source lives in src/, with Next.js routes under src/app (UI) and API handlers in src/app/api—API files orchestrate services only. Domain logic, database queries, and external integrations reside in src/services (always use database.ts). HTTP clients belong in src/clients, React hooks in src/hooks, reusable UI in src/components, and shared utilities or types in src/lib. Operational helpers live in scripts/, Prisma schema and migrations in prisma/, and static assets in public/.
Build, Test & Operational Commands
Start local development with npm run dev (Turbopack). Build production artifacts using npm run build and serve them via npm run start. Lint and type-check with npm run lint; run formatting verification through npm run prettier:check or fix issues via npm run prettier:format. Operational validations include npm run backup:list, npm run backup:verify, and cache utilities such as npm run cache:stats.
Coding Style & Naming
Prettier and ESLint (next/core-web-vitals) enforce a 2-space, TypeScript-first style. Components and hooks use PascalCase, utilities use camelCase, and types live in src/types or src/lib. Co-locate component-specific assets near their implementation. Never bypass lint-staged; rely on Husky to run formatting before commits.
Architecture & Data Flow Rules
Keep business logic out of the frontend: components, hooks, and clients may orchestrate UI state but must call services for domain decisions. Services are the only place for PostgreSQL queries and must expose typed interfaces with transaction handling. API routes validate input, call services, and return typed JSON—no raw SQL or business rules inline. Prefer Server Actions for straightforward mutations that require fast UI feedback; keep complex workflows, public endpoints, and integrations in API routes. Clients wrap HTTP calls, reuse the base HTTP client, and return typed responses.
Styling & Theme System
All theming goes through CSS variables defined in src/app/globals.css and applied by ThemeContext. Do not use Tailwind dark: toggles or hard-coded colors; prefer var(--token) (and color-mix when translucency is needed). Keep semantic naming (--card, --primary, --muted) and extend the palette by adding variables instead of branching logic in components.
Testing & Verification
Today’s automated coverage relies on linting plus targeted scripts (e.g., npm run test:story-points, npm run test:jira-fields). When adding data flows or schedulers, contribute new headless scripts under scripts/ and document manual QA steps in PRs. Name fixtures after the feature they back (backlog-config.json) and ensure linting passes before review.
TODO Tracking & Workflow
If you complete an item in TODO.md, immediately flip its checkbox to checked without altering wording; add timestamps for major milestones. Mirror progress across sub-tasks and note blockers to keep the list trustworthy.
Commit & PR Expectations
Follow the conventional prefixes visible in history (feat:, refactor:, chore:) with concise, action-oriented subjects. Group related changes per commit, documenting architectural context in the body when touching shared layers. Pull requests must summarize behavior changes, link issues, and attach screenshots for UI updates or schema diffs for Prisma changes. Confirm migrations, linting, formatting, and relevant scripts succeed before requesting review.