Engineering

Context

We need to store a code knowledge graph: functions, classes, modules, and their relationships (calls, imports, inherits, implements). The query pattern is traversal-heavy — "find all callers of this function up to depth 3" — not aggregation-heavy.

Decision

Use Neo4j (Community Edition, self-hosted) as the primary store for the code knowledge graph. Each codebase gets a logical namespace via a repo_id property on every node. Cypher is the query language.

Why

• Native graph traversal is orders of magnitude faster than SQL JOINs at depth >2
• Cypher is expressive for code relationship queries ("find all functions this module transitively depends on")
• APOC library gives us path algorithms (shortest path, all paths) out of the box
• Community Edition is free, avoiding vendor lock-in for early product phase

Trade-offs

Alternatives considered

• PostgreSQL with pg_graph: Familiar but graph traversal via recursive CTEs is slow and verbose at depth >3
• Amazon Neptune: Managed but expensive and vendor lock-in at pre-revenue stage
• DGraph: Open source but smaller community and less mature Cypher-compatible tooling

Context

Cerebro needs to call LLM APIs (OpenAI, Anthropic, etc.) to generate code and answer questions. The question is whether we act as a proxy (calling the API with our own keys and billing users for token usage) or require users to supply their own API keys (BYOK).

Decision

Bring Your Own Key (BYOK). Users configure their own API keys in the VS Code plugin settings. Cerebro never stores keys server-side — they are used exclusively within the user's local plugin context and never transmitted to our backend.

Why

• Eliminates LLM cost as a COGS line item — our pricing covers context infrastructure, not token pass-through
• Users already have API keys for Copilot, Cursor, etc. — no friction
• No regulatory risk around storing API keys or proxying model calls on behalf of users
• Users get the exact model they want (GPT-4o, Claude Sonnet, etc.) without us managing model upgrades

Trade-offs

Alternatives considered

• Proxy model (our keys, metered billing): Higher operational complexity, token cost management, and PCI/data compliance overhead at pre-revenue stage

Context

Cerebro's core intelligence is a multi-step pipeline: parse query → retrieve from Neo4j → retrieve from Qdrant → merge context → call LLM → stream response. This pipeline needs to be deterministic, debuggable, and interruptible (for streaming). Simple sequential code gets messy when steps have conditional branches, retries, and partial state.

Decision

Use LangGraph (from LangChain) to model the pipeline as an explicit state machine. Each step is a node; edges define transitions. State is typed (TypedDict). The graph is compiled once at startup and re-used per request. Streaming is handled via LangGraph's built-in async generator support.

Why

• Explicit state makes debugging straightforward — you can see exactly what state entered each node
• Conditional edges model "if vector search returns nothing, expand to graph traversal" cleanly
• LangGraph's checkpointing allows resumable pipelines for long-running ingestion jobs
• Async streaming is first-class, not a bolt-on

Trade-offs

Alternatives considered

• Raw async Python: Simpler for linear flows but gets complicated fast with branching and retries
• Prefect / Airflow: Better for batch data pipelines, not designed for low-latency per-request inference
• Haystack pipelines: Too opinionated about the RAG pattern, harder to integrate with our custom Neo4j traversal step

Context

Cerebro is a multi-tenant product — each user's codebase must be isolated from other users'. The question is whether to use physical isolation (separate database instances per user) or logical isolation (a shared instance with namespace/tenant-ID filtering on all queries).

Decision

Logical namespace isolation. Every Neo4j node and Qdrant vector has a user_id property. Every query is scoped by this property. In Qdrant, this is a filter condition on every collection search. In Neo4j, the repo_id property gates every Cypher traversal. A single shared Neo4j instance and a single Qdrant collection serve all users in the current phase.

Why

• Physical isolation (DB per user) is operationally expensive — provisioning, monitoring, backups multiply with user count
• At early user counts (<1000), logical isolation is secure and dramatically simpler
• Migration path to physical isolation exists if a high-value enterprise customer requires it

Trade-offs

Alternatives considered

• Physical DB per user: Secure by default but operationally unscalable before we have dedicated infra team
• Schema-level isolation in PostgreSQL: Viable for relational data, not applicable to Neo4j or Qdrant

Context

The backend spans multiple distinct concerns: parsing source code, managing the knowledge graph, serving the AI pipeline, and handling user accounts. Without explicit architecture boundaries, these tend to collapse into a monolithic service where Neo4j queries appear inside auth handlers and vice versa.

Decision

Apply Clean Architecture (ports and adapters) with Domain-Driven Design bounded contexts. The four contexts are: Ingestion (parse + ingest code into the graph), Intelligence (the LangGraph query pipeline), Identity (auth and user management), and Billing (plans and subscriptions). Each context has its own domain model and communicates with others through defined interfaces — never direct imports across boundaries.

Why

• Ingestion and Intelligence can evolve independently — swapping the AST parser doesn't affect the query pipeline
• Testability: each context can be tested with mocked ports, no need to spin up Neo4j for auth tests
• Billing is isolated from product logic — easier to swap Stripe for another provider later

Trade-offs

Alternatives considered

• Single FastAPI app, no layers: Faster to start but we've seen this become unmaintainable once the LangGraph pipeline grew complex
• Full microservices from day one: Too much operational overhead (service discovery, inter-service auth) before product-market fit