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

# Architecture

> How public brains are structured, secured, and queried.

This page explains what a public brain actually is under the hood: how its content is organised, who can read it, and what happens when you run a query. If you just want the endpoints, start with the [Brains overview](/brains/overview).

## The data model

A brain is a graph. Versuno builds it by indexing a source, then storing the result as two kinds of objects:

* **Containers** are the folders. They give the brain its shape, and a container can hold other containers.
* **Nodes** are the content. Every node has a `type`, and the two you will see most are `page` (a document) and `chunk` (a section of a page).

Containers nest into a tree, and nodes hang off the containers:

```
Brain "Next.js Docs"
├─ Container "Routing"
│  ├─ Container "App Router"
│  │  └─ Node (page) "Dynamic Routes"
│  └─ Node (page) "Linking and Navigating"
└─ Container "Data Fetching"
   └─ Node (page) "Caching"
```

A page-type node can sit at the root of the brain with no container above it, which is why nodes carry both a `containerId` (the folder they belong to) and a `brainId` (the brain they belong to).

### Inside a page

A single page breaks down further when you query it. A page contains **chunks**, and each chunk contains **chunk parts**. The chunk part is the smallest retrievable unit, and it is what a query scores for relevance:

```
Page "Dynamic Routes"
└─ Chunk "The params prop"
   ├─ Chunk part 1   relevancy 0.82
   └─ Chunk part 2   relevancy 0.71
```

You never have to assemble this yourself. A query returns the pages, chunks, and chunk parts it matched, plus a `graph_tree` that ties them back together in this shape.

## Public versus private

Every brain has an `isPublic` flag. It controls who is allowed to read the brain and everything inside it:

* A **public brain** is readable by anyone with a valid API key. The same applies to its containers and its nodes.
* A **private brain** is readable only by its owner.

A "public brain" is not a separate object type. It is an ordinary brain with `isPublic` set to true, which opens up read access at the database level for that brain and its whole subtree.

## Access and security

Reading a brain and querying a brain take two different paths, and they resolve different sets of brains. This is the part worth understanding before you build against the API.

```
Read   GET /brains/...           your API key        →  public brains + brains you own
Query  POST /brains/{id}/query   shared service id   →  public brains
```

* **Read endpoints** run as you. They use your API key, so row-level security lets you see any public brain plus any brain you own.
* **Query endpoints** do not run as you. They run under a shared Versuno service identity, so they resolve public brains by ID regardless of who owns them. Your API key is still required and still validated at the edge, but it is not the identity that reads the data.

Two consequences fall out of this:

1. You cannot currently query a private brain through the public API, even one you own, because the query runs as the service identity rather than as you.
2. The brain-level query is **metered**. Each call to `POST /brains/{id}/query` counts against your usage. The container-scoped query is not metered.

Everything here is read only. There is no public endpoint to write into a brain yet.

## How a query runs

When you call a query endpoint, this is the pipeline it goes through:

<Steps>
  <Step title="Embed the query">
    Your natural-language `query` is turned into a vector embedding.
  </Step>

  <Step title="Search the brain">
    A vector search ranks chunk parts across the brain by similarity. You can narrow it to a single container, bias it toward named `entities`, and cap the results with `limit` (1 to 20, default 5).
  </Step>

  <Step title="Assemble the graph">
    The matched chunk parts are rolled back up into their chunks and pages, and the relations between objects are attached as `graph_context`.
  </Step>

  <Step title="Return the result">
    You get the matched `objects` (pages, chunks, chunk parts), the `graph_tree` linking them, the relations, and `metadata` with the embedding and query latencies.
  </Step>
</Steps>

Because the query always returns HTTP 200, check the `success` and `error` fields in the envelope rather than the status code. See the [Query a brain](/brains/overview) endpoint for the full request and response shape.

## Where this is heading

Public brains are the read-only, public foundation of something larger. The roadmap is universal memory: a per-user context brain that any model, tool, or agent can both read from and write to, persisting what your AI learns across sessions and across tools. The query pipeline and graph model on this page are the groundwork that layer is being built on.