CepatEdge

Appearance

AI agent playbooks (CepatEdge) ​

This folder is written for automated coding agents (and humans using them). It summarizes how this repo is structured, how to change it safely, and where to look before editing. It does not duplicate every ADR; it points to them.

Read order ​

  1. git.md — How to review changes, align commit messages with project style, and ship coherent commits.
  2. patterns.md — Monorepo layout, domain separation, type safety, and common boundaries (web vs workers).
  3. locales.md — i18n translation workflow, preserve policy, typed keys, lazy locale loading, and AI-assisted locale polishing prompt guidance.
  4. Deeper docs live under ../frontend/ (SPA, domains, i18n, API) and ../architecture/ (ADRs, systems).
  5. System admin & analytics (repo root): SYSTEM.md defines /system/* observability (logs, audit, monitor, settings). DASHBOARD.md defines dashboard analytics and cache/settings wiring—read after SYSTEM.md when changing those areas.

Recent i18n doc + tooling changes ​

  • docs/frontend/i18n/examples.md now reflects the updated CLI flow: pnpm locales:validate, then pnpm locales:validate:quality, then pnpm locales:cleanup; use pnpm locales:ci in CI.
  • apps/web/scripts/locales/manage/cleanup.ts was expanded to detect key drift (unused keys in en.json + extra keys in other locales) using static heuristics.
  • docs/frontend/i18n/cleanup.md, docs/frontend/i18n/delete.md, and docs/frontend/i18n/examples.md were added/updated to guide agent-safe locale workflows.

Operating principles ​

  • Prefer existing patterns over inventing new ones. If a feature fits “shared page + role route,” follow ../frontend/features/shared-vs-role-pages.md.
  • Types are leverage: workers expose typed services and route handlers; the web app consumes typed API shapes where they exist. Extend apps/*/src/types/ rather than scattering any.
  • Domain separation: UI and routes live under apps/web/src/domains/<role-or-shared>/; API logic lives in apps/worker/src/. Do not move business rules into React components when they belong in workers.
  • Small, reviewable commits with messages that match git.md. Large “kitchen sink” commits make rollback and blame harder.

When you are unsure ​

  • Search the codebase for an existing analogue (e.g. another maintenance route, another dashboard card).
  • Read the nearest ADR under docs/architecture/decisions/.
  • Prefer asking for a missing product rule over guessing security or permission behavior.