MicroFish/.claude/rules/dev-guidelines.md

# Salestech Products Development Guidelines

Always obey the **Salestech Products Development Guidelines**. These are
enforceable rules — non-compliant code will be rejected during review.

## Source
- Notion (Live, authoritative): https://candylabs.notion.site/development-guidelines
- Connect via Notion MCP server (HTTP requires JS, so MCP is the only reliable way).
- Always consult the live document for the latest version.

## Summary (snapshot — refer to live doc for authority)

### 1. Code Formatting & Style
- 4 spaces indentation (JS/TS and Python). No tabs.
- Max **120 chars** per line.
- No trailing whitespace; files end with a single newline.
- JS/TS: no semicolons (`semi: false`), single quotes, trailing commas
  where valid in ES5, omit parens around single arrow params.
- Python: double quotes for strings.
- Tools: Prettier + ESLint (JS/TS, npm); Ruff (Python, uv).

### 2. Naming
- JS/TS: `camelCase` vars/funcs, `PascalCase` classes/types/enums,
  `UPPER_SNAKE_CASE` constants, `kebab-case` filenames, boolean prefixes
  `is`/`has`/`should`.
- Python: `snake_case` vars/funcs/files, `PascalCase` classes,
  `UPPER_SNAKE_CASE` constants, `_leading_underscore` private.
- No abbreviations (except `id`, `url`, `http`).
- No single-letter vars (except short lambda / loop indices).
- No Hungarian notation.

### 3. Comments & Documentation
- Don't comment the obvious — comment the *why*.
- `TODO:` / `FIXME:` must include a ticket reference.
- JS/TS: JSDoc on all exported functions, classes, interfaces.
- Python: Google-style docstrings on all public funcs/classes/modules.

### 4. Git Workflow
- Branch: `<type>/<ticket-id>-<short-description>` (`feat`, `fix`,
  `chore`, `docs`, `hotfix`).
- Commits: **Conventional Commits**, lowercase, imperative, max 72 chars,
  no period, no `Co-Authored-By:` watermarks.
- PRs: linked to a ticket, ≥1 human approval, all CI checks pass,
  squash-merge feature branches, delete source branch after merge.
- Never commit directly to `main` / `dev`; never force-push shared
  branches; never commit secrets.

### 5. React & TypeScript
- Component file order: imports → types → constants → helpers →
  component.
- Named exports only; function declarations for components.
- Props types named `<ComponentName>Props`; never `React.FC`.
- Hooks start with `use`; never call hooks conditionally.
- React Router v7: file/config-based routes (don't mix), use
  `loader`/`action`, `useNavigate`, `useSearchParams`, `<Link>`,
  `<Outlet>`.
- TanStack Query: centralized query key factories, never `fetch`/`axios`
  in components, always handle loading/success/error, prefer
  `invalidateQueries` over manual cache.
- State priority: URL → TanStack Query → component state → Context.
  Never duplicate server state into local state.

### 6. Tailwind 4 (CSS-only config)
- Component styles inline as Tailwind classes; no separate CSS modules
  per component.
- Use `clsx` for dynamic classes.
- Mobile-first responsive prefixes.
- `prettier-plugin-tailwindcss` ordering required.
- No `!important` (Tailwind `!`) without justification + comment.
- `main.css` only for `@import`, `@theme`, global base styles, third-
  party overrides.

### 7. Folder Structure
- Layer-based for frontend (`api/`, `components/`, `hooks/`,
  `pages/`, `queries/`, `routes/`, `types/`, `utils/`).
- FastAPI: `routers/`, `models/`, `schemas/`, `services/`; Pydantic
  `BaseSettings`; business logic in services not routers.
- Django: `config/`, `apps/<app>/`, `common/`; one app per domain;
  business logic in `services.py`; max one migration per app per PR;
  custom User model from day 1.
- Django templates: `snake_case.html` in `templates/<app_name>/`,
  partials prefixed `_`, `{% extends %}` mandatory, DjHTML formatter,
  `{% url %}` for all URLs.
- Root directory: configuration files only.
- README.md mandatory (setup, env vars, run/test).

### 8. Accessibility
- WCAG 2.1 Level AA.
- Semantic HTML; one `<h1>` per page; no skipped heading levels.
- All images need `alt`; decorative use `alt=""`.
- 4.5:1 / 3:1 contrast minimums.
- Every form input: visible `<label>` linked via `htmlFor`/`id`.
- Keyboard accessible; native `<button>` for actions, `<a>`/`<Link>`
  for navigation.
- Custom widgets: implement WAI-ARIA pattern + keyboard handling.
- Modals trap focus and restore on close.

### 9. Environments, Secrets, Dependencies
- `.env` never committed; `.env.example` always provided and current.
- Client-exposed vars use framework prefix (e.g., `VITE_`).
- Never commit / log secrets. Rotate immediately if leaked.
- Verify a new dep is necessary; prefer well-maintained, MIT/Apache/BSD.
- No trivial deps (`is-odd`, `left-pad`, etc.).
- Lock files always committed, exact versions, no `latest` ranges.
- Dev dependencies separated from production.

### 10. Security
- Validate/sanitize all user input on the server.
- Parameterize all DB queries.
- Auto-escape templating; no `dangerouslySetInnerHTML` / `| safe`
  without lead approval.
- AuthN/AuthZ on every endpoint.
- HTTPS only (except `localhost`).
- Security headers: CSP, X-Content-Type-Options, HSTS, X-Frame-Options.
- CSRF protection (Django middleware / secure token storage on SPA).
- Rate-limit auth endpoints + public APIs.
- Never log passwords/tokens/PII.
- Principle of least privilege for service accounts.

### 11. Infrastructure
- `compose.yaml` (no `version:` key) for Docker Compose.

### 12. Enforcement
- Pre-commit hooks: format, lint, import order.
- CI: tests, lint, type check, build, dep audit.
- Code review: naming, docs, architecture, a11y.
- Non-compliance is grounds for requesting changes.

---
**When in doubt, fetch the latest version from Notion via the MCP server
and follow it — these guidelines evolve.**