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

# Architecture

> How Ragrails is organized.

Ragrails is built in layers:

```
core → SDK → CLI / REST API
```

## Package layout

```
ragrails/
  core/
    stg_01_ingestors/
    stg_02_chunker/
    stg_03_embedder/
    stg_04_storing/
    stg_05_retriever/
    stg_06_chat/
  interfaces/
    sdk/
    cli/
    server/
```

## Layers

| Layer        | Responsibility                                                                          |
| ------------ | --------------------------------------------------------------------------------------- |
| **core**     | Pipeline logic, provider models, and vector store adapters. Not part of the public API. |
| **SDK**      | The `RagRails` class, the Python-facing interface that wraps the core.                  |
| **CLI**      | Terminal commands. A thin layer that translates shell input into SDK calls.             |
| **REST API** | FastAPI server. Route services call the SDK, never the core directly.                   |

## Design principles

* **SDK-first** - the CLI and REST API are both built on the SDK. Behavior lives in the SDK and core, not in the interface layers.
* **In-memory SDK** - SDK methods accept and return Python objects. The CLI bridges file I/O to the in-memory SDK.
* **Typed results** - every SDK method returns a frozen dataclass result with consistent count, item, and error fields.