Add backend/CLAUDE.md contributor guide

[beastoin]

The backend/ directory is the most complex part of the Omi codebase (45+ routers, 5 microservices, Firestore/Redis/Pinecone/Neo4j) but has no CLAUDE.md. The root CLAUDE.md covers high-level rules and app/CLAUDE.md + desktop/CLAUDE.md provide subdirectory-specific guidance, but backend contributors (both AI agents and open-source developers) lack a focused operational guide. This leads to repeated mistakes around import hierarchy, WebSocket auth patterns, test registration, and service architecture.

Current Behavior

• No backend-specific contributor documentation exists
• Backend rules are scattered across root CLAUDE.md (brief) and tribal knowledge
• Common mistakes recur: in-function imports, HTTPException in WS handlers, missing test.sh registration, unsanitized logging, wrong black flags
• External contributors have no guide for local dev setup, service architecture, or database patterns

Expected Behavior

A concise backend/CLAUDE.md that inherits from root CLAUDE.md and provides backend-specific operational guidance, matching the style and depth of app/CLAUDE.md.

Affected Areas

File	Description
backend/CLAUDE.md	New file — backend contributor guide

Solution

Create backend/CLAUDE.md covering:

• Inheritance: Inherits all rules from root ../CLAUDE.md
• Directory structure: What each top-level folder does (database/, utils/, routers/, models/, charts/)
• Service architecture: backend-listen (GKE), pusher, diarizer, agent-proxy, vad (deployment targets + dependencies)
• Database layer: Firestore (primary), Redis (cache/rate-limit), Pinecone (vectors), Neo4j (knowledge graph)
• Auth patterns: Firebase ID tokens, ADMIN_KEY for local dev, WebSocket auth with WebSocketException(code=1008)
• Import rules: Top-level only, strict hierarchy (database → utils → routers → main.py)
• Testing: test.sh as source of truth, test-preflight.sh, mock patterns (patch.object over string-based patch), new tests must be added to test.sh
• Logging security: sanitize() / sanitize_pii() from utils.log_sanitizer
• Local development: Prerequisites, env setup, port-forwards for diarizer/VAD
• Common gotchas: Python 3.11 (no 3.12+ syntax), black --skip-string-normalization, WAL opus encoding, Firestore field gating, asyncio.sleep not time.sleep
• Formatting: black --line-length 120 --skip-string-normalization
• Rate limiting: Per-UID Redis Lua scripts, fail-open pattern

Files to Modify

• backend/CLAUDE.md (new)

Impact

Documentation-only — no code changes. Improves contributor onboarding and reduces repeated review feedback on common mistakes.

---

This issue was drafted by AI on behalf of @beastoin