# RARA architecture

## Responsibility

RARA is responsible for RAG behavior and quality while remaining independent of
the physical storage and model products used to implement that behavior.

```text
Consumers
    |
    v
RAG data plane
  retrieve | answer | trace
    |
    +--> retrieval backend integrations
    +--> embedding/reranking providers
    +--> generation providers

Control plane
  projects | knowledge bases | workflows | datasets
  evaluations | releases | schedules | lineage
    |
    +--> PostgreSQL control state
    +--> artifact store integrations
    +--> Go/Python executors
```

## Planes

### Control plane

The control plane owns lifecycle state: projects, integrations, knowledge
bases, datasets, artifacts, workflows, evaluations, schedules, and releases.

### RAG data plane

The RAG API owns online retrieval and answer behavior. A request resolves a
knowledge base and release alias, applies the release's retrieval policy, and
returns evidence and release identity. `answer` additionally invokes a selected
generation provider and may stream output over SSE.

### Adaptation plane

Python executors curate evaluation and training data and later run LoRA/QLoRA
jobs. The control plane owns job state and artifacts; Python owns ML library
execution.

## Storage

PostgreSQL stores control state and lineage only. Large artifacts live in an
`ArtifactStore`. Retrieval indexes live in a `RetrievalBackend`. Both are
selected through integration instances with versioned capabilities and secret
references.

Integrations implement typed, product-neutral ports for source change streams,
index publication and retrieval, embeddings, reranking, generation, artifacts,
and secret resolution. The initial registry is compile-time Go composition;
out-of-process ML execution uses the versioned Protobuf executor contract.

## Initial safety defaults

- release promotion is explicit
- production indexes are immutable
- updates build candidate artifacts before promotion
- source deletion and ACL changes are tracked through lineage
- integration secrets are referenced, never stored in integration config
- stored RAG traces always have an expiry; raw query and answer fields remain optional