# opensanctions/yente architecture

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

- Interactive diagram: https://gitdiagram.com/opensanctions/yente
- Repository: https://github.com/opensanctions/yente

## Overview

Yente is an asynchronous HTTP API for searching, retrieving, and matching FollowTheMoney entities from configured datasets. A request reaches a dedicated search, match, or reconciliation router; matching builds candidate queries, searches the index, then scores results. Separately, catalog and entity-data loading feed index maintenance, which writes searchable indices through the configured Elasticsearch or OpenSearch provider. The README also documents on-premises use and custom watchlists. Some subsystem paths and links are included from the source index or README because their implementations were not excerpted.

Main entry points: [`yente/search/indexer.py`](https://github.com/opensanctions/yente/blob/main/yente/search/indexer.py) (Index maintenance), [`yente/app.py`](https://github.com/opensanctions/yente/blob/main/yente/app.py) (FastAPI application), [`yente/search/search.py`](https://github.com/opensanctions/yente/blob/main/yente/search/search.py) (Search execution), [`yente/routers/match.py`](https://github.com/opensanctions/yente/blob/main/yente/routers/match.py) (Match endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["FastAPI application<br/>[app.py]"]
  node_search_route["Search endpoint<br/>[search.py]"]
  node_match_route["Match endpoint<br/>[match.py]"]
  node_reconcile_route["Reconcile endpoint<br/>[reconcile.py]"]
  node_admin_route["Admin endpoints<br/>[admin.py]"]
end

subgraph group_matching["Search and Matching"]
  node_query_builder["Query construction<br/>[queries.py]"]
  node_search_exec["Search execution<br/>[search.py]"]
  node_scoring["Match scoring<br/>[scoring.py]"]
  node_response_models["Response models<br/>[common.py]"]
end

subgraph group_data["Data and Catalog"]
  node_entity_model["Entity model<br/>[entity.py]"]
  node_dataset_model["Dataset model<br/>[dataset.py]"]
  node_catalog["Dataset catalog<br/>[__init__.py]"]
  node_manifest["Manifest handling<br/>[manifest.py]"]
  node_data_loader["Entity data loading<br/>[loader.py]"]
  node_data_updater["Dataset updates<br/>[updater.py]"]
end

subgraph group_index["Index and Providers"]
  node_indexer["Index maintenance<br/>[indexer.py]"]
  node_mapping["Index mapping<br/>[mapping.py]"]
  node_provider_factory["Provider selection<br/>[__init__.py]"]
  node_provider_base["Search provider interface<br/>[base.py]"]
  node_elastic["Elasticsearch provider<br/>[elastic.py]"]
  node_opensearch["OpenSearch provider<br/>[opensearch.py]"]
end

node_client(("API client"))
node_search_store[("Search index")]
node_data_sources["Configured data sources"]

node_client -->|"sends requests"| node_app
node_app -->|"registers route"| node_search_route
node_app -->|"registers route"| node_match_route
node_app -->|"registers route"| node_reconcile_route
node_app -->|"registers route"| node_admin_route
node_search_route -->|"builds query"| node_query_builder
node_search_route -->|"executes search"| node_search_exec
node_search_route -->|"returns results"| node_response_models
node_match_route -->|"builds candidates"| node_query_builder
node_match_route -->|"retrieves candidates"| node_search_exec
node_match_route -->|"scores candidates"| node_scoring
node_match_route -->|"formats matches"| node_response_models
node_reconcile_route -->|"builds query"| node_query_builder
node_reconcile_route -->|"retrieves entities"| node_search_exec
node_reconcile_route -->|"scores candidates"| node_scoring
node_query_builder -->|"uses index fields"| node_mapping
node_search_exec -->|"queries provider"| node_provider_factory
node_search_exec -->|"constructs entities"| node_entity_model
node_scoring -->|"scores entity data"| node_entity_model
node_app -->|"starts reindexing"| node_indexer
node_admin_route -->|"requests indexing"| node_indexer
node_admin_route -->|"reads catalog"| node_catalog
node_catalog -->|"loads manifest"| node_manifest
node_dataset_model -.->|"resolves entity data"| node_data_sources
node_data_loader -->|"loads dataset entities"| node_dataset_model
node_indexer -->|"reads datasets"| node_catalog
node_indexer -.->|"loads entity data"| node_data_loader
node_indexer -->|"checks updates"| node_data_updater
node_indexer -->|"indexes entities"| node_entity_model
node_indexer -->|"creates mappings"| node_mapping
node_indexer -->|"writes through"| node_provider_factory
node_provider_factory -->|"selects provider"| node_elastic
node_provider_factory -->|"selects provider"| node_opensearch
node_elastic -->|"implements interface"| node_provider_base
node_opensearch -->|"implements interface"| node_provider_base
node_elastic -.->|"reads and writes"| node_search_store
node_opensearch -.->|"reads and writes"| node_search_store
node_search_exec -.->|"searches index"| node_search_store

click node_app "https://github.com/opensanctions/yente/blob/main/yente/app.py"
click node_search_route "https://github.com/opensanctions/yente/blob/main/yente/routers/search.py"
click node_match_route "https://github.com/opensanctions/yente/blob/main/yente/routers/match.py"
click node_reconcile_route "https://github.com/opensanctions/yente/blob/main/yente/routers/reconcile.py"
click node_admin_route "https://github.com/opensanctions/yente/blob/main/yente/routers/admin.py"
click node_query_builder "https://github.com/opensanctions/yente/blob/main/yente/search/queries.py"
click node_search_exec "https://github.com/opensanctions/yente/blob/main/yente/search/search.py"
click node_scoring "https://github.com/opensanctions/yente/blob/main/yente/scoring.py"
click node_response_models "https://github.com/opensanctions/yente/blob/main/yente/data/common.py"
click node_entity_model "https://github.com/opensanctions/yente/blob/main/yente/data/entity.py"
click node_dataset_model "https://github.com/opensanctions/yente/blob/main/yente/data/dataset.py"
click node_catalog "https://github.com/opensanctions/yente/blob/main/yente/data/__init__.py"
click node_manifest "https://github.com/opensanctions/yente/blob/main/yente/data/manifest.py"
click node_data_loader "https://github.com/opensanctions/yente/blob/main/yente/data/loader.py"
click node_data_updater "https://github.com/opensanctions/yente/blob/main/yente/data/updater.py"
click node_indexer "https://github.com/opensanctions/yente/blob/main/yente/search/indexer.py"
click node_mapping "https://github.com/opensanctions/yente/blob/main/yente/search/mapping.py"
click node_provider_factory "https://github.com/opensanctions/yente/blob/main/yente/provider/__init__.py"
click node_provider_base "https://github.com/opensanctions/yente/blob/main/yente/provider/base.py"
click node_elastic "https://github.com/opensanctions/yente/blob/main/yente/provider/elastic.py"
click node_opensearch "https://github.com/opensanctions/yente/blob/main/yente/provider/opensearch.py"

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_app,node_search_route,node_match_route,node_reconcile_route,node_admin_route,node_client toneBlue
class node_query_builder,node_search_exec,node_scoring,node_response_models,node_search_store toneAmber
class node_entity_model,node_dataset_model,node_catalog,node_manifest,node_data_loader,node_data_updater toneMint
class node_indexer,node_mapping,node_provider_factory,node_provider_base,node_elastic,node_opensearch toneRose
class node_data_sources toneIndigo
```

## Components

### HTTP API

- [FastAPI application](https://github.com/opensanctions/yente/blob/main/yente/app.py): `yente/app.py`
- [Search endpoint](https://github.com/opensanctions/yente/blob/main/yente/routers/search.py): `yente/routers/search.py`
- [Match endpoint](https://github.com/opensanctions/yente/blob/main/yente/routers/match.py): `yente/routers/match.py`
- [Reconcile endpoint](https://github.com/opensanctions/yente/blob/main/yente/routers/reconcile.py): `yente/routers/reconcile.py`
- [Admin endpoints](https://github.com/opensanctions/yente/blob/main/yente/routers/admin.py): `yente/routers/admin.py`

### Search and Matching

- [Query construction](https://github.com/opensanctions/yente/blob/main/yente/search/queries.py): `yente/search/queries.py`
- [Search execution](https://github.com/opensanctions/yente/blob/main/yente/search/search.py): `yente/search/search.py`
- [Match scoring](https://github.com/opensanctions/yente/blob/main/yente/scoring.py): `yente/scoring.py`
- [Response models](https://github.com/opensanctions/yente/blob/main/yente/data/common.py): `yente/data/common.py`

### Data and Catalog

- [Entity model](https://github.com/opensanctions/yente/blob/main/yente/data/entity.py): `yente/data/entity.py`
- [Dataset model](https://github.com/opensanctions/yente/blob/main/yente/data/dataset.py): `yente/data/dataset.py`
- [Dataset catalog](https://github.com/opensanctions/yente/blob/main/yente/data/__init__.py): `yente/data/__init__.py`
- [Manifest handling](https://github.com/opensanctions/yente/blob/main/yente/data/manifest.py): `yente/data/manifest.py`
- [Entity data loading](https://github.com/opensanctions/yente/blob/main/yente/data/loader.py): `yente/data/loader.py`
- [Dataset updates](https://github.com/opensanctions/yente/blob/main/yente/data/updater.py): `yente/data/updater.py`

### Index and Providers

- [Index maintenance](https://github.com/opensanctions/yente/blob/main/yente/search/indexer.py): `yente/search/indexer.py`
- [Index mapping](https://github.com/opensanctions/yente/blob/main/yente/search/mapping.py): `yente/search/mapping.py`
- [Provider selection](https://github.com/opensanctions/yente/blob/main/yente/provider/__init__.py): `yente/provider/__init__.py`
- [Search provider interface](https://github.com/opensanctions/yente/blob/main/yente/provider/base.py): `yente/provider/base.py`
- [Elasticsearch provider](https://github.com/opensanctions/yente/blob/main/yente/provider/elastic.py): `yente/provider/elastic.py`
- [OpenSearch provider](https://github.com/opensanctions/yente/blob/main/yente/provider/opensearch.py): `yente/provider/opensearch.py`

### Other components

- **API client**
- **Search index**
- **Configured data sources**

## Connections

- API client → FastAPI application: sends requests (evidence: `yente/app.py`)
- FastAPI application → Search endpoint: registers route (evidence: `yente/app.py`)
- FastAPI application → Match endpoint: registers route (evidence: `yente/app.py`)
- FastAPI application → Reconcile endpoint: registers route (evidence: `yente/app.py`)
- FastAPI application → Admin endpoints: registers route (evidence: `yente/app.py`)
- Search endpoint → Query construction: builds query (evidence: `yente/routers/search.py`)
- Search endpoint → Search execution: executes search (evidence: `yente/routers/search.py`)
- Search endpoint → Response models: returns results (evidence: `yente/routers/search.py`)
- Match endpoint → Query construction: builds candidates (evidence: `yente/routers/match.py`)
- Match endpoint → Search execution: retrieves candidates (evidence: `yente/routers/match.py`)
- Match endpoint → Match scoring: scores candidates (evidence: `yente/routers/match.py`)
- Match endpoint → Response models: formats matches (evidence: `yente/routers/match.py`)
- Reconcile endpoint → Query construction: builds query (evidence: `yente/routers/reconcile.py`)
- Reconcile endpoint → Search execution: retrieves entities (evidence: `yente/routers/reconcile.py`)
- Reconcile endpoint → Match scoring: scores candidates (evidence: `yente/routers/reconcile.py`)
- Query construction → Index mapping: uses index fields (evidence: `yente/search/queries.py`)
- Search execution → Provider selection: queries provider (evidence: `yente/search/search.py`)
- Search execution → Entity model: constructs entities (evidence: `yente/search/search.py`)
- Match scoring → Entity model: scores entity data (evidence: `yente/scoring.py`)
- FastAPI application → Index maintenance: starts reindexing (evidence: `yente/app.py`)
- Admin endpoints → Index maintenance: requests indexing (evidence: `yente/routers/admin.py`)
- Admin endpoints → Dataset catalog: reads catalog (evidence: `yente/routers/admin.py`)
- Dataset catalog → Manifest handling: loads manifest (evidence: `yente/data/__init__.py`)
- Dataset model → Configured data sources: resolves entity data (evidence: `yente/data/dataset.py`)
- Entity data loading → Dataset model: loads dataset entities (evidence: `yente/data/loader.py`)
- Index maintenance → Dataset catalog: reads datasets (evidence: `yente/search/indexer.py`)
- Index maintenance → Entity data loading: loads entity data (evidence: `yente/search/indexer.py`)
- Index maintenance → Dataset updates: checks updates (evidence: `yente/search/indexer.py`)
- Index maintenance → Entity model: indexes entities (evidence: `yente/search/indexer.py`)
- Index maintenance → Index mapping: creates mappings (evidence: `yente/search/indexer.py`)
- Index maintenance → Provider selection: writes through (evidence: `yente/search/indexer.py`)
- Provider selection → Elasticsearch provider: selects provider (evidence: `yente/provider/__init__.py`)
- Provider selection → OpenSearch provider: selects provider (evidence: `yente/provider/__init__.py`)
- Elasticsearch provider → Search provider interface: implements interface (evidence: `yente/provider/elastic.py`)
- OpenSearch provider → Search provider interface: implements interface (evidence: `yente/provider/opensearch.py`)
- Elasticsearch provider → Search index: reads and writes
- OpenSearch provider → Search index: reads and writes
- Search execution → Search index: searches index
