1. Arquitetura Geral — Arquitetura Ideal de Ingestion

Este documento descreve a arquitetura ideal de ingestion para sistemas RAG: como os dados entram, mudam, são versionados, validados e ficam prontos para retrieval.

Regra de Ouro: Nunca enviar uma fonte diretamente para vector DB / SQL / graph sem passar por um modelo canónico intermédio. PDF, YAML, CSV, SQL, graph export → primeiro normalizar para DocumentRecord, StructuredRecord ou GraphRecord.

---

Diagrama de Fluxo

+---------------------------+
|        Data Sources       |
|---------------------------|
| YAML / JSON / CSV         |
| Markdown / TXT / PDF      |
| SQL tables                |
| Graph exports / APIs      |
+-------------+-------------+
              |
              v
+-------------+-------------+
|   Source Connectors       |
|---------------------------|
| file loader               |
| sql extractor             |
| graph loader              |
| api loader (future)       |
+-------------+-------------+
              |
              v
+-------------+-------------+
|   Change Detection        |
|---------------------------|
| new / updated / deleted   |
| checksum / hash / diff    |
| schema diff               |
| metadata diff             |
+-------------+-------------+
              |
              v
+-------------+-------------+
| Canonical Normalization   |
|---------------------------|
| DocumentRecord            |
| StructuredRecord          |
| GraphRecord               |
| Entity / Relation model   |
+-------------+-------------+
              |
      +-------+--------+--------------------+
      |                |                    |
      v                v                    v
+-----+------+  +------+-------+    +-------+------+
| Doc Pipeline|  | SQL Pipeline |    | Graph Pipeline|
|-------------|  |--------------|    |---------------|
| parse       |  | validate      |    | node mapping  |
| chunk plan  |  | upsert/SCD    |    | edge mapping  |
| versioning  |  | schema sync   |    | relation diff |
| embed later |  | history       |    | versioning    |
+-----+------+  +------+-------+    +-------+------+
      |                |                    |
      +-------+--------+--------------------+
              |
              v
+-------------+-------------+
| Metadata / Registry       |
|---------------------------|
| versions                  |
| lineage                   |
| dependencies              |
| active status             |
| freshness                 |
+-------------+-------------+
              |
              v
+-------------+-------------+
| Observability / Audit     |
|---------------------------|
| ingestion runs            |
| changed assets            |
| failures                  |
| reindex triggers          |
| impacted retrieval views  |
+---------------------------+

---

Os 6 Blocos Principais

Bloco A — Data Sources

Aqui entram todas as fontes possíveis.

Observação: Nem todas as fontes são "documentos". Não tratar tudo como texto para embeddings.

---

Bloco B — Source Connectors / Loaders

Cada tipo de fonte tem um loader próprio.

Responsabilidade: Só ler e extrair. Não decidir chunking, não decidir retrieval.

Exemplo de saída:

{
  "source_id": "docs/security_policy.md",
  "source_type": "markdown",
  "raw_content": "...",
  "metadata": {
    "path": "...",
    "modified_at": "...",
    "checksum": "..."
  }
}

---

Bloco C — Change Detection

Um dos blocos mais importantes. Responde:

Tipos de deteção por fonte:

---

Bloco D — Canonical Normalization

Ver 02-CANONICAL-MODEL para detalhes completos.

Resumo: três tipos internos — DocumentRecord, StructuredRecord, GraphRecord.

---

Bloco E — Pipelines por Backend (Processors + Index/Storage Update)

Cada pipeline processa Records e escreve no backend correspondente (Index/Storage Update).

Ver 03-PIPELINES.

---

Bloco F — Metadata + Observability

• Registry: asset_id, version, status, lineage
• Lineage: de onde vem, para onde vai
• Dependencies: que assets dependem de quê
• Observability: runs, failures, reindex triggers

Ver 05-REGISTRY-DEPENDENCIES e 08-OBSERVABILITY.

---

Ligação com Retrieval

A saída da ingestion alimenta o retrieval:

Ingestion (chunks, SQL, graph) → Registry (versions, lineage, freshness)
    → Retrieval consulta: vector store, Postgres, Neo4j
    → Metadados (version, is_active, valid_to) permitem freshness-aware retrieval

Ver 07-RETRIEVAL e pasta ../retrieval/ para a arquitetura de retrieval.