# mertvbaran/recall architecture

> Architecture diagram of the GitHub repository mertvbaran/recall, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mertvbaran/recall
- Repository: https://github.com/mertvbaran/recall

## Overview

Recall is a local, retrieval-only search tool for a personal Markdown wiki: it returns ranked passages and sources, and can flag questions outside the notes rather than generating answers. Indexing parses vault documents, chunks them, embeds them, and persists a searchable index; querying embeds the question, retrieves candidates, and applies a separate confidence gate. Users interact through a CLI or Streamlit dashboard. The dashboard also records gate corrections and presents evaluation reports. Pipeline and interface relationships are documented; some implementation details are unsampled, so uncertain wiring is omitted.

Main entry points: [`src/build_index.py`](https://github.com/mertvbaran/recall/blob/master/src/build_index.py) (Index builder), [`src/query.py`](https://github.com/mertvbaran/recall/blob/master/src/query.py) (Query CLI), [`src/dashboard.py`](https://github.com/mertvbaran/recall/blob/master/src/dashboard.py) (Streamlit dashboard), [`src/embedder.py`](https://github.com/mertvbaran/recall/blob/master/src/embedder.py) (Embedder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_indexing["Indexing"]
  node_indexbuilder["Index builder<br/>[build_index.py]"]
  node_loader["Vault loader<br/>[loader.py]"]
  node_chunkers["Chunk strategies<br/>[chunkers.py]"]
  node_embedder["Embedder<br/>[embedder.py]"]
end

subgraph group_retrieval["Retrieval"]
  node_retrieval["Vector search<br/>[store.py]"]
  node_gate["Scope confidence gate<br/>[reranker.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_query["Query CLI<br/>[query.py]"]
  node_dashboard["Streamlit dashboard<br/>[dashboard.py]"]
  node_feedback[("Gate feedback log<br/>[feedback.py]")]
end

subgraph group_localdata["Local data and models"]
  node_foundry["Foundry Local"]
  node_cache[("Embedding cache<br/>[embedder.py]")]
  node_indexstore[("Vector index<br/>[store.py]")]
  node_reports["Evaluation reports"]
end

node_vault["Markdown vault"]
node_user(("User"))

node_vault -->|"indexes"| node_indexbuilder
node_indexbuilder -->|"loads documents"| node_loader
node_indexbuilder -->|"chunks documents"| node_chunkers
node_indexbuilder -->|"embeds chunks"| node_embedder
node_indexbuilder -->|"persists index"| node_indexstore
node_embedder -->|"requests vectors"| node_foundry
node_embedder -->|"reads/writes vectors"| node_cache
node_user -->|"asks question"| node_query
node_query -->|"loads index"| node_indexstore
node_query -->|"embeds question"| node_embedder
node_query -->|"searches vectors"| node_retrieval
node_query -->|"checks candidate scope"| node_gate
node_user -->|"asks question"| node_dashboard
node_dashboard -->|"searches vectors"| node_retrieval
node_dashboard -->|"checks candidate scope"| node_gate
node_dashboard -->|"records corrections"| node_feedback
node_dashboard -->|"reads reports"| node_reports

click node_indexbuilder "https://github.com/mertvbaran/recall/blob/master/src/build_index.py"
click node_loader "https://github.com/mertvbaran/recall/blob/master/src/loader.py"
click node_chunkers "https://github.com/mertvbaran/recall/blob/master/src/chunkers.py"
click node_embedder "https://github.com/mertvbaran/recall/blob/master/src/embedder.py"
click node_cache "https://github.com/mertvbaran/recall/blob/master/src/embedder.py"
click node_indexstore "https://github.com/mertvbaran/recall/blob/master/src/store.py"
click node_query "https://github.com/mertvbaran/recall/blob/master/src/query.py"
click node_dashboard "https://github.com/mertvbaran/recall/blob/master/src/dashboard.py"
click node_retrieval "https://github.com/mertvbaran/recall/blob/master/src/store.py"
click node_gate "https://github.com/mertvbaran/recall/blob/master/src/reranker.py"
click node_feedback "https://github.com/mertvbaran/recall/blob/master/src/feedback.py"
click node_reports "https://github.com/mertvbaran/recall/tree/master/results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_indexbuilder,node_loader,node_chunkers,node_embedder,node_user toneBlue
class node_retrieval,node_gate toneAmber
class node_query,node_dashboard,node_feedback toneMint
class node_foundry,node_cache,node_indexstore,node_reports toneRose
class node_vault toneIndigo
```

## Components

### Indexing

- [Index builder](https://github.com/mertvbaran/recall/blob/master/src/build_index.py): `src/build_index.py`
- [Vault loader](https://github.com/mertvbaran/recall/blob/master/src/loader.py): `src/loader.py`
- [Chunk strategies](https://github.com/mertvbaran/recall/blob/master/src/chunkers.py): `src/chunkers.py`
- [Embedder](https://github.com/mertvbaran/recall/blob/master/src/embedder.py): `src/embedder.py`

### Retrieval

- [Vector search](https://github.com/mertvbaran/recall/blob/master/src/store.py): `src/store.py`
- [Scope confidence gate](https://github.com/mertvbaran/recall/blob/master/src/reranker.py): `src/reranker.py`

### User interfaces

- [Query CLI](https://github.com/mertvbaran/recall/blob/master/src/query.py): `src/query.py`
- [Streamlit dashboard](https://github.com/mertvbaran/recall/blob/master/src/dashboard.py): `src/dashboard.py`
- [Gate feedback log](https://github.com/mertvbaran/recall/blob/master/src/feedback.py): `src/feedback.py`

### Local data and models

- **Foundry Local**
- [Embedding cache](https://github.com/mertvbaran/recall/blob/master/src/embedder.py): `src/embedder.py`
- [Vector index](https://github.com/mertvbaran/recall/blob/master/src/store.py): `src/store.py`
- [Evaluation reports](https://github.com/mertvbaran/recall/tree/master/results): `results`

### Other components

- **Markdown vault**
- **User**

## Connections

- Markdown vault → Index builder: indexes
- Index builder → Vault loader: loads documents
- Index builder → Chunk strategies: chunks documents
- Index builder → Embedder: embeds chunks
- Index builder → Vector index: persists index
- Embedder → Foundry Local: requests vectors
- Embedder → Embedding cache: reads/writes vectors
- User → Query CLI: asks question
- Query CLI → Vector index: loads index
- Query CLI → Embedder: embeds question
- Query CLI → Vector search: searches vectors
- Query CLI → Scope confidence gate: checks candidate scope
- User → Streamlit dashboard: asks question
- Streamlit dashboard → Vector search: searches vectors
- Streamlit dashboard → Scope confidence gate: checks candidate scope
- Streamlit dashboard → Gate feedback log: records corrections
- Streamlit dashboard → Evaluation reports: reads reports