> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reflections.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# System overview

> High-level architecture of the Reflections platform — a voice-first AI agent that retrieves and reasons over a personal knowledge graph.

Reflections is a voice-first AI agent backed by a personal knowledge graph. Users talk to their "reflection" — an LLM that retrieves and reasons over chunked documents, entities, and temporal facts ingested from uploaded sources.

## What the platform does

When a user speaks, the platform:

1. Bootstraps a voice session through a managed provider (ElevenLabs Conversations API).
2. Retrieves relevant facts, entities, and document chunks from the knowledge graph during the conversation via server-tool callbacks.
3. Ingests new sources in the background — extracting facts, evaluating them, and promoting approved knowledge into the graph.

The result is a continuously learning agent that remembers what you tell it, with safety gates that prevent unvetted information from entering active truth.

## Tech stack

| Layer           | Technology                                                |
| --------------- | --------------------------------------------------------- |
| Monorepo        | pnpm 10.15+ with Turborepo                                |
| Runtime         | Node.js >= 22, ESM throughout                             |
| Language        | TypeScript in strict mode, tsup builds                    |
| Database        | Supabase Postgres with pgvector for embeddings            |
| Background jobs | Inngest for durable step functions                        |
| Voice           | ElevenLabs Conversations API                              |
| Auth            | Clerk JWT (frontend) + bearer tokens (service-to-service) |
| Frontend        | Next.js (web), native Swift (iOS)                         |
| Validation      | Zod schemas shared across all layers                      |

## Two execution planes

The system separates work into two execution planes with different latency and safety requirements.

<CardGroup cols={2}>
  <Card title="Realtime plane" icon="bolt">
    Voice session bootstrap, server-tool callbacks, and knowledge retrieval. Read-only against truth
    tables (facts, entities, chunks, sources). Optimized for low latency.
  </Card>

  <Card title="Background plane" icon="gears">
    Source ingestion, fact extraction, evaluation, and patch application. Facts enter as candidates
    and become active only after passing the eval gate.
  </Card>
</CardGroup>

This separation ensures that write-side failures in the background pipeline never impact user-facing voice response times. See [Two-plane architecture](/architecture/two-plane-architecture) for a full explanation.

## DB query segregation

The `@reflection/db` package exposes three entrypoints that enforce access boundaries at the import level:

* **`./queries/read`** — used by the realtime plane for retrieval queries.
* **`./queries/write`** — used for mutations like conversation logging.
* **`./queries/admin`** — used exclusively by background workers for ingestion, patch application, and evaluation writes.

ESLint rules block `admin` imports from the realtime and API planes. File-scan tests provide an additional enforcement layer that cannot be disabled with inline comments.

## Dependency direction

Packages never depend on apps. Apps consume packages only through published entrypoints.

```
apps/api  ─────┐
apps/workers ──┤
apps/web  ─────┼──▶  packages/brain-core
apps/ios  ─────┘     packages/db
                     packages/schemas
                     packages/vendors
                     packages/shared
                     packages/eval
                     packages/api-client
```

This rule is enforced by the monorepo structure, ESLint configuration, and architecture guard scripts. See [Package map](/architecture/package-map) for the full breakdown.

## Learn more

<CardGroup cols={2}>
  <Card title="Two-plane architecture" icon="layer-group" href="/architecture/two-plane-architecture">
    Why the system separates realtime inference from background learning.
  </Card>

  <Card title="Boundary matrix" icon="shield-halved" href="/architecture/boundaries">
    What each plane is allowed and forbidden to do.
  </Card>

  <Card title="System invariants" icon="lock" href="/architecture/invariants">
    Non-negotiable rules, complexity budgets, and release blockers.
  </Card>

  <Card title="Package map" icon="diagram-project" href="/architecture/package-map">
    Every app and package in the monorepo with its purpose and dependencies.
  </Card>

  <Card title="Knowledge graph" icon="brain" href="/architecture/knowledge-graph">
    Temporal facts, the patch lifecycle, and the aspect taxonomy.
  </Card>

  <Card title="Decision records" icon="scale-balanced" href="/decisions/index">
    25 ADRs documenting core architectural choices.
  </Card>
</CardGroup>