Add CLAUDE.md with architecture and workflow guidance

[chedevlooper-creator]

Summary

Adds a CLAUDE.md (none existed) documenting the codebase for AI assistants.

• Big-picture architecture: 1 Next.js app + 7 independent Fastify services (ports 3001–3007) + @pcp/db / @pcp/shared, communicating over HTTP / Redis / BullMQ.
• Commands: pnpm-9 workspace fan-outs, per-package filters, drizzle DB workflow, infra bring-up, smoke checks.
• Conventions & gotchas verified against source: mandatory tenant isolation, Zod env validation, strict TS (noUncheckedIndexedAccess), intentional vitest version split, no apps/api (stale README), gitignored infra/docker/.env, CI order.

Cross-checked against the actual code (services, schema, scripts, CI) rather than the partially-stale README.

Test plan

• Verify commands in CLAUDE.md run as documented
• Confirm service ports and responsibilities match current code

https://claude.ai/code/session_01XQBiqnh3V7qCDwRtb2XKrP

---

Generated by Claude Code

[octopus-review]

🐙 Octopus Review — PR #5

Summary

This PR adds a CLAUDE.md file — a project orientation guide for Claude Code (and similar AI coding agents) working in the repo. It consolidates architecture, commands, conventions, and CI flow into a single reference document. The content closely mirrors AGENTS.md and the existing planning docs, with light editing for clarity.

Score

Category	Score	Notes
Security	N/A	Documentation only; no code changes
Code Quality	N/A	Documentation only
Performance	N/A	Documentation only
Error Handling	N/A	Documentation only
Consistency	4/5	Mostly accurate; a few factual gaps vs. ground truth
Overall	4/5	Solid reference doc with minor inaccuracies to address

Risk Assessment

Metric	Value
Overall Risk	🟢 Low
Complexity	Low
Test Coverage Impact	N/A
Breaking Change	No

Positive Highlights

• Accurate stale-reference handling: Proactively calls out the dead apps/api / :4000 / /health curl block in the README — exactly what downstream agents need to avoid wasted effort.
• Concise service table: The port/responsibility table is the right format for quick agent orientation and matches the actual repo layout precisely.
• Vitest split warning preserved: Carrying over the vitest@^4.1.5 vs ^1.4.0 split caveat from AGENTS.md is the kind of footgun detail that saves real debugging time.

Important Files Changed

Filename	Overview
CLAUDE.md	New AI-agent orientation doc; covers commands, architecture, conventions, CI, and reference links. Mirrors AGENTS.md with prose reorganized for Claude Code's context window pattern.

---

Checklist

• No hardcoded secrets or credentials
• No unnecessary dependencies added
• API changes are backward compatible (N/A — docs only)
• Factual accuracy vs. ground truth verified (see findings below)

Last reviewed commit: 9ba6d68

[codesnifai]

🤖 CodeSnif AI Review

This PR introduces a new CLAUDE.md file that documents the architecture and workflow of the AI assistants codebase, detailing the structure of the application and its services. It provides guidance on commands, conventions, and important considerations for developers working with the codebase.

---

Risk Level	🟢 LOW
Merge Advice	merge now
Breaking Changes	✅ None detected

📋 Walkthrough

• Added CLAUDE.md to document architecture and workflow.
• Included details on commands, conventions, and gotchas.

🔍 Pre-merge Checks

• ❌ Documentation changes typically do not affect code functionality.
• ❌ No code changes are introduced, only a new markdown file.

⚠️ Concerns

• The mergeable state is unstable, indicating potential issues that need to be addressed before merging.

✨ Highlights

• Comprehensive documentation enhances understanding of the codebase.
• Clear architecture overview aids in onboarding new developers.

🧪 Testing Notes

Review the CLAUDE.md for clarity and completeness, ensuring it accurately reflects the current architecture and workflow.

Powered by CodeSnif · AI-powered PR analysis

[octopus-review]

1 file reviewed, 4 findings | View scores & details

🟡💡 Additional findings

Severity	File	Title	Description
🟡	CLAUDE.md:L96	vitest version pinning is inverted — auth/workspace are NOT on ^4.1.5	The doc states: 'services/auth and services/workspace pin vitest@^4.1.5; other services use ^1.4.0'. This contradicts AG…
💡	CLAUDE.md:L22	pnpm smoke:local description is inaccurate	The comment 'scripts/baseline-smoke.mjs → typecheck → lint → test → web smoke' implies smoke:local runs the full CI chai…
💡	CLAUDE.md:L21	Missing note that packages/shared has no test script	The doc says 'pnpm test — vitest where defined (web uses Playwright; shared has none)'. This is correct about shared, bu…
💡	CLAUDE.md:L129	AGENTS.md sync reminder is one-directional	The final line says 'AGENTS.md holds the same surgical notes for other agents — keep the two in sync when conventions ch…

_{Reviewed by Octopus Review, an AI-powered PR review tool.}

[chedevlooper-creator]

Re Octopus Review findings — verified against source:

• 🟡 vitest pinning "inverted": false positive. Confirmed from the actual package.json files: services/auth and services/workspace are on vitest@^4.1.5; agent, memory, runtime, browser, publish are on ^1.4.0. This matches both the doc and AGENTS.md (no contradiction). No change.
• 💡 The remaining notes (smoke:local wording, packages/shared test, AGENTS.md sync direction) are minor and the statements are accurate as written. No change.

---

Generated by Claude Code