diff --git a/.gitignore b/.gitignore index dc1e76fe..8d629067 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ blob-report/ # IDE / tool scratch .superpowers/ .claude/ +CLAUDE.md docs/superpowers/ PRD.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 7b6285a3..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,102 +0,0 @@ -# Stirling-Image - -Open-source, self-hostable image manipulation suite. Docker-first deployment. - -## Tech Stack - -| Layer | Technology | -|-------|-----------| -| Frontend | React 19, Vite 6, Tailwind CSS 4, Zustand, react-router-dom v7 | -| Backend | Fastify 5, tsx (no compile step in dev), Sharp | -| Database | SQLite via Drizzle ORM (better-sqlite3) | -| AI/ML | Python sidecar (rembg, RealESRGAN, PaddleOCR, MediaPipe, LaMa) | -| Docs | VitePress | -| Testing | Vitest (unit/integration), Playwright (e2e) | -| CI/CD | GitHub Actions, semantic-release, Docker multi-arch | -| Linting | Biome (format + lint in one pass) | - -## Monorepo Structure - -``` -apps/ - api/ # Fastify backend (port 13490) - web/ # Vite + React frontend (port 1349, proxies /api to 13490) - docs/ # VitePress documentation -packages/ - shared/ # Constants, types, i18n strings - image-engine/ # Sharp-based image operations - ai/ # Python sidecar bridge for ML models -tests/ - unit/ # Vitest unit tests - integration/ # Vitest integration tests (full API) - e2e/ # Playwright e2e specs (13 files) - fixtures/ # Small test images -``` - -## Key Conventions - -- **Simplicity over complexity** — do not over-engineer -- **Double quotes**, **semicolons**, **2-space indent** (enforced by Biome) -- **ES modules** in all workspaces (`"type": "module"`) -- Conventional commits for semantic-release (`feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`) -- API tool routes in `apps/api/src/routes/tools/` -- Tool UI components in `apps/web/src/components/tools/` -- i18n strings in `packages/shared/src/i18n/en.ts` -- Zod for all API input validation - -## Commands - -```bash -pnpm dev # Start all dev servers (web + api) -pnpm build # Build all workspaces -pnpm typecheck # TypeScript check across monorepo -pnpm lint # Biome lint + format check -pnpm lint:fix # Biome auto-fix lint + format issues -pnpm test # Vitest unit + integration tests -pnpm test:unit # Unit tests only -pnpm test:integration # Integration tests only -pnpm test:e2e # Playwright e2e tests -pnpm test:coverage # Tests with coverage report -``` - -## Database - -SQLite via Drizzle ORM. Migrations in `apps/api/drizzle/`. - -```bash -cd apps/api && npx drizzle-kit generate # Generate migration from schema changes -cd apps/api && npx drizzle-kit migrate # Apply pending migrations -``` - -Schema: `apps/api/src/db/schema.ts` — tables: users, sessions, settings, jobs, apiKeys, pipelines. - -## Do Not Modify Config Files - -Biome, TypeScript, and editor config files are protected by hooks. Fix the code to satisfy the linter/compiler, not the other way around. This prevents a common AI failure mode where rules get weakened instead of code getting fixed. - -## Model Routing for Subagents - -When spawning subagents via the Agent tool, use the cheapest model that can handle the task: - -- **Haiku**: File search, simple lookups, grep operations, quick checks -- **Sonnet**: Standard development, test writing, refactoring, code review -- **Opus**: Complex architecture decisions, multi-file debugging, planning - -This saves significant cost without losing quality on the main session. - -## Strategic Compaction - -When context gets large, compact at logical phase boundaries: - -- **Good times to compact**: After research and before planning. After debugging and before implementing the fix. After completing a major feature. -- **Bad times to compact**: Mid-implementation. While actively debugging. During a multi-step refactor. -- **Survives compaction**: This CLAUDE.md, active tasks, git state, memory files -- **Lost on compaction**: Intermediate reasoning, file contents previously read, conversation flow - -## Security - -- Never commit `.env`, credentials, or API keys -- Validate user input at API boundaries with Zod schemas -- Use parameterized queries (Drizzle ORM handles this) -- SVG sanitization is already in place for uploads -- Rate limiting is configured on the API