Add backend/CLAUDE.md contributor guide

[beastoin]

Closes #6232. The backend/ directory is the most complex part of the Omi codebase (45+ routers, 5 microservices, Firestore/Redis/Pinecone/Neo4j) but had no CLAUDE.md. This adds a focused contributor guide sourced from operational experience across the team (mon, hiro, kenji), covering service architecture, database patterns, auth, testing, local dev, and common gotchas.

Link related issues: #6232

---

This pr was drafted by AI on behalf of @beastoin

[greptile-apps]

Greptile Summary

This PR adds backend/CLAUDE.md, a focused operational playbook for the backend directory — the most complex part of the Omi codebase. The guide covers service architecture, database patterns (Firestore, Redis, Pinecone, Neo4j), auth patterns (HTTP + WebSocket), testing conventions, local dev setup, and a curated list of production gotchas.

The content is accurate against the codebase and well-organized. One actionable issue was found:

• Rate Limiting import is missing context: The rate limiting example uses auth.with_rate_limit(auth.get_current_user_uid, ...) where auth is the aliased utils.other.endpoints module (from utils.other import endpoints as auth). Without showing this import, a contributor familiar with the HTTP Endpoints section (which uses from utils.other.endpoints import get_current_user_uid directly) will incorrectly assume auth refers to firebase_admin.auth, leading to an AttributeError at runtime.
• The database/memories.py inline comment uses the phrase "Example domain module" which could be misread as indicating the file is a placeholder rather than a real, actively-used module.

Confidence Score: 4/5

Safe to merge after fixing the missing import in the Rate Limiting example, which would otherwise misdirect contributors trying to apply the pattern.

One P1 issue exists: the Rate Limiting code snippet omits the required from utils.other import endpoints as auth import, making the example copy-paste-incorrect and likely to confuse contributors who follow the HTTP Endpoints import style shown just above it. All other content is accurate, well-sourced, and adds real operational value.

backend/CLAUDE.md — Rate Limiting example (lines 116–122) needs the missing import alias added.

Important Files Changed

Filename	Overview
backend/CLAUDE.md	New contributor guide for the backend; content is accurate and operationally useful, but the Rate Limiting example omits the critical from utils.other import endpoints as auth import required to use the auth.with_rate_limit pattern shown.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Mobile([Mobile / Desktop Client])

    subgraph GKE["GKE — prod-omi-backend"]
        BL[backend-listen\nmain.py]
    end

    subgraph CR["Cloud Run"]
        PU[pusher\npusher/main.py]
        DI[diarizer\ndiarizer/main.py]
        AP[agent-proxy\nagent-proxy/main.py]
    end

    subgraph Modal["Modal — GPU"]
        VAD[vad]
        NJ[notifications-job\ncron]
    end

    subgraph Stores["Shared Stores"]
        FS[(Firestore)]
        RD[(Redis)]
        PC[(Pinecone)]
        N4[(Neo4j)]
    end

    DG[Deepgram STT]
    VM[User Agent VMs\nprivate IP :8080]

    Mobile -- REST / WS --> BL
    BL -- WS pub/sub --> PU
    BL --> DI
    BL --> VAD
    BL --> DG
    PU --> DI
    PU --> DG
    AP -- WS --> VM
    Mobile -- agent WS --> AP

    BL --- FS & RD & PC & N4
    PU --- FS & RD

Loading

_{Reviews (1): Last reviewed commit: "Add backend/CLAUDE.md contributor guide ..." | Re-trigger Greptile}

[greptile-apps]

Missing import for auth alias in Rate Limiting example

The rate limiting snippet uses auth.with_rate_limit(auth.get_current_user_uid, ...), but the auth here is actually the utils.other.endpoints module imported as an alias — not firebase_admin.auth. Without seeing the import, a contributor will naturally assume auth refers to firebase_admin.auth (as shown in the HTTP Endpoints section above), and be confused when with_rate_limit doesn't exist on it.

Across the codebase, the pattern is consistently:

from utils.other import endpoints as auth

uid: str = Depends(auth.with_rate_limit(auth.get_current_user_uid, "chat:send_message"))

The HTTP Endpoints example in the same section uses from utils.other.endpoints import get_current_user_uid (a direct import), which is inconsistent with the Rate Limiting example's aliased style. Adding the import makes the pattern self-contained and unambiguous.

[greptile-apps]

Misleading "Example domain module" label for database/memories.py

The comment # Example domain module (conversations.py, users.py, etc.) could be read as "this file is just an example/placeholder." The intent seems to be "this is one instance of the domain module pattern, alongside conversations.py, users.py, etc." — but the phrasing is ambiguous and could lead contributors to disregard the file.

A clearer label would be:

Suggested change

	memories.py # Example domain module (conversations.py, users.py, etc.)
	memories.py # Domain module (same pattern: conversations.py, users.py, etc.)

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[beastoin]

lgtm