> ## 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.

# Package map

> Every app and package in the Reflections monorepo — what it does, what it depends on, and how Turborepo orchestrates builds.

The Reflections monorepo uses pnpm workspaces with Turborepo for build orchestration. The codebase is split into deployable **apps** and shared **packages**, with strict rules governing how they depend on each other.

## Apps

Apps are the deployable units of the platform. Each app serves a distinct runtime concern.

| App            | Description                                                                                                                                                     | Plane      |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `apps/api`     | Hono API server. Handles session bootstrap, server-tool callbacks for the voice provider, webhook receivers, and auth/role derivation.                          | Realtime   |
| `apps/workers` | Inngest-powered background pipeline. Runs source ingestion, fact extraction, evaluation, and patch application as durable step functions.                       | Background |
| `apps/web`     | Next.js frontend. Provides the user dashboard, knowledge graph visualization, source management, and session interface.                                         | Client     |
| `apps/ios`     | Native Swift iOS app. Voice interaction interface with knowledge graph visualization and session management. Built with Xcode, outside the pnpm/turbo pipeline. | Client     |

## Packages

Packages contain shared logic consumed by apps through published entrypoints. They never depend on apps.

| Package               | Description                                                                                                                                                                                              | Key consumers                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `packages/brain-core` | Retrieval and reasoning logic. Builds retrieval queries, ranks results, and assembles context for LLM prompts.                                                                                           | `apps/api`                            |
| `packages/db`         | Database queries with read/write/admin segregation. Exposes three entrypoints: `./queries/read` (realtime retrieval), `./queries/write` (session mutations), `./queries/admin` (worker-only operations). | `apps/api`, `apps/workers`            |
| `packages/schemas`    | Shared Zod schemas for API contracts, event payloads, ingestion lifecycle states, and the aspect taxonomy. The cross-layer type contract.                                                                | All apps and packages                 |
| `packages/vendors`    | Third-party API clients for Anthropic (LLM) and OpenAI (embeddings). Isolates vendor SDK dependencies so no other package imports them directly.                                                         | `apps/workers`, `packages/brain-core` |
| `packages/shared`     | Utilities, environment config (`env.ts`), structured logger, timing helpers, aspect classification, and scoring formulas.                                                                                | All apps and packages                 |
| `packages/eval`       | Fact evaluation logic. Scores candidate facts for confidence and checks for contradictions with existing knowledge.                                                                                      | `apps/workers`                        |
| `packages/api-client` | Typed HTTP client for the Reflections API. Generated from Zod schemas to maintain type safety across the network boundary.                                                                               | `apps/web`, `apps/ios`                |

## Dependency direction

The dependency graph flows in one direction: apps depend on packages, never the reverse.

```
┌─────────────────────────────────────────────────────┐
│                       Apps                          │
│  api    workers    web    ios                        │
└──────────────────────┬──────────────────────────────┘
                       │ depends on
                       ▼
┌─────────────────────────────────────────────────────┐
│                     Packages                        │
│  brain-core  db  schemas  vendors  shared  eval     │
│  api-client                                         │
└─────────────────────────────────────────────────────┘
```

<Warning>
  Packages must never import from `apps/*`. This is enforced by the monorepo structure (packages do
  not list apps as dependencies) and verified by architecture guard scripts in CI.
</Warning>

### Import rules within packages

Not all packages can import from each other freely:

* **`packages/brain-core`** cannot import from `@reflection/db/queries/admin` — this enforces the read-only realtime invariant.
* **`packages/vendors`** is the only package allowed to import directly from `@anthropic-ai/sdk` and `openai`. All other packages access vendor APIs through `@reflection/vendors`.
* **`packages/shared`** has no dependencies on other `@reflection/*` packages — it sits at the bottom of the dependency graph.
* **`packages/schemas`** depends only on Zod — it defines the cross-layer type contract with no runtime dependencies.

## How Turborepo orchestrates builds

Turborepo manages the build pipeline through the `turbo.json` configuration at the repo root.

<AccordionGroup>
  <Accordion title="Build ordering">
    Turborepo uses `dependsOn` declarations in `turbo.json` to build packages before the apps that consume them. When you run `pnpm build`, Turborepo:

    1. Builds leaf packages first (`packages/schemas`, `packages/shared`).
    2. Builds packages that depend on those (`packages/db`, `packages/vendors`, `packages/eval`, `packages/brain-core`, `packages/api-client`).
    3. Builds apps last (`apps/api`, `apps/workers`, `apps/web`).

    All packages use `tsup` for bundling, producing ESM output.
  </Accordion>

  <Accordion title="Caching">
    Turborepo caches build outputs based on file hashes. If a package's source files have not changed,
    its build step is skipped and the cached output is reused. This makes incremental builds fast —
    typically only the changed packages and their downstream consumers rebuild.
  </Accordion>

  <Accordion title="Task pipelines">
    Key Turborepo tasks and what they run:

    * **`build`** — `tsup` (packages) or framework build (apps). Respects dependency ordering.
    * **`lint`** — ESLint across all workspaces in parallel.
    * **`typecheck`** — `tsc --noEmit` across all workspaces in parallel.
    * **`test`** — Vitest across all workspaces in parallel.

    The `pnpm check` command runs `format:check`, `lint`, `typecheck`, `test`, and `build` in the correct order as the local CI gate.
  </Accordion>
</AccordionGroup>

<Note>
  The iOS app (`apps/ios`) is a pure Xcode project and does not participate in the pnpm/Turborepo
  pipeline. It is built and tested separately via `xcodebuild`. The contract between iOS and the API
  is maintained through shared Zod schemas that generate Swift-compatible types.
</Note>

## Enforcement

Import boundaries between packages are enforced at three layers:

1. **ESLint** — `no-restricted-imports` rules block deep imports, admin query access from the realtime plane, and direct vendor SDK imports.
2. **Architecture guard** — `simplicity-guard.mjs` runs in CI and catches dynamic imports that bypass ESLint.
3. **File-scan tests** — dedicated tests in affected packages verify import restrictions and cannot be disabled with inline comments.

See the [boundary matrix](/architecture/boundaries) for per-plane allowed and forbidden operations.

## Further reading

* [ADR-0001](/decisions/adr-0001) — the original decision record for the monorepo and package boundary design.
* [Two-plane architecture](/architecture/two-plane-architecture) — how the realtime and background planes map to apps.
* [System invariants](/architecture/invariants) — the non-negotiable rules that package boundaries enforce.