# nordmanndev/lui architecture

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

- Interactive diagram: https://gitdiagram.com/nordmanndev/lui
- Repository: https://github.com/nordmanndev/lui

## Overview

LUI is a .NET library for typo-tolerant autocomplete over SQLite/FTS5, with embedded indexes or indexes linked to application-owned tables. The main workflow opens an index, configures a query, executes search, and returns ranked hits. Separate capabilities include bulk synchronization, typo-dictionary warmup, and ASP.NET Core/worker hosting. Relationships below are limited to those shown in the excerpts, SOURCE INDEX references, or README; unsampled implementation details are represented only where the tree supports the subsystem.

Main entry points: [`src/Nordmann.LUI/Querying/QueryRunner.cs`](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/QueryRunner.cs) (Query execution), [`src/Nordmann.LUI/LuiCatalog.cs`](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiCatalog.cs) (Catalog API), [`src/Nordmann.LUI/Indexes/EmbeddedIndex.cs`](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/EmbeddedIndex.cs) (Embedded index), [`src/Nordmann.LUI/Indexes/LinkedIndex.cs`](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/LinkedIndex.cs) (Linked index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog and indexes"]
  node_catalog_api["Catalog API<br/>[LuiCatalog.cs]"]
  node_embedded["Embedded index<br/>[EmbeddedIndex.cs]"]
  node_linked["Linked index<br/>[LinkedIndex.cs]"]
  node_bulk_sync["Index synchronization<br/>[EmbeddedSync.cs]"]
end

subgraph group_search["Query and ranking"]
  node_query_api["Query builder<br/>[LuiQuery.cs]"]
  node_query_runner["Query execution<br/>[QueryRunner.cs]"]
  node_candidates["Candidate reading<br/>[CandidateReader.cs]"]
  node_typo_correction["Typo correction<br/>[TypoCorrection.cs]"]
  node_ranking["Ranking and hits<br/>[Ranker.cs]"]
  node_results["Search results<br/>[LuiResult.cs]"]
end

subgraph group_data["SQLite and schema"]
  node_database[("SQLite access<br/>[Database.cs]")]
  node_embedded_source["Embedded schema<br/>[EmbeddedSource.cs]"]
  node_linked_source["Linked schema<br/>[LinkedSource.cs]"]
  node_definitions["Index definitions<br/>[IndexDefinition.cs]"]
end

subgraph group_support["Normalization and hosting"]
  node_normalizer["Text normalization<br/>[Normalizer.cs]"]
  node_typo_dictionary["Typo dictionary<br/>[TypoDictionary.cs]"]
  node_hosting["Hosting integration"]
  node_warmup["Hosted warmup"]
end

node_app(("Application"))

node_app -->|"opens catalog"| node_catalog_api
node_catalog_api -->|"opens index"| node_embedded
node_catalog_api -->|"opens linked"| node_linked
node_app -->|"configures search"| node_query_api
node_query_api -->|"executes on"| node_embedded
node_query_api -->|"executes on"| node_linked
node_embedded -->|"uses runner"| node_query_runner
node_linked -->|"uses runner"| node_query_runner
node_query_runner -->|"reads SQLite"| node_database
node_query_runner -->|"reads candidates"| node_candidates
node_query_runner -->|"requests correction"| node_typo_correction
node_query_runner -->|"ranks candidates"| node_ranking
node_query_runner -->|"uses dictionary"| node_typo_dictionary
node_query_runner -->|"returns hits"| node_results
node_embedded -->|"indexes content"| node_embedded_source
node_linked -->|"reads linked table"| node_linked_source
node_catalog_api -->|"initializes store"| node_database
node_embedded_source -->|"uses definition"| node_definitions
node_linked_source -->|"uses definition"| node_definitions
node_embedded -->|"syncs entries"| node_bulk_sync
node_query_runner -->|"normalizes query"| node_normalizer
node_typo_dictionary -->|"normalizes words"| node_normalizer
node_app -->|"registers services"| node_hosting
node_hosting -->|"registers warmup"| node_warmup
node_warmup -->|"warms catalog"| node_catalog_api

click node_catalog_api "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiCatalog.cs"
click node_embedded "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/EmbeddedIndex.cs"
click node_linked "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/LinkedIndex.cs"
click node_bulk_sync "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/EmbeddedSync.cs"
click node_query_api "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiQuery.cs"
click node_query_runner "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/QueryRunner.cs"
click node_candidates "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/CandidateReader.cs"
click node_typo_correction "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/TypoCorrection.cs"
click node_ranking "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/Ranker.cs"
click node_results "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiResult.cs"
click node_database "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Storage/Database.cs"
click node_embedded_source "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Schema/EmbeddedSource.cs"
click node_linked_source "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Schema/LinkedSource.cs"
click node_definitions "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Schema/IndexDefinition.cs"
click node_normalizer "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Normalization/Normalizer.cs"
click node_typo_dictionary "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Typos/TypoDictionary.cs"
click node_hosting "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI.Hosting/LuiServiceCollectionExtensions.cs"
click node_warmup "https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI.Hosting/Hosting/LuiWarmupService.cs"

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_catalog_api,node_embedded,node_linked,node_bulk_sync toneBlue
class node_query_api,node_query_runner,node_candidates,node_typo_correction,node_ranking,node_results toneAmber
class node_database,node_embedded_source,node_linked_source,node_definitions toneMint
class node_normalizer,node_typo_dictionary,node_hosting,node_warmup toneRose
class node_app toneIndigo
```

## Components

### Catalog and indexes

- [Catalog API](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiCatalog.cs): `src/Nordmann.LUI/LuiCatalog.cs`
- [Embedded index](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/EmbeddedIndex.cs): `src/Nordmann.LUI/Indexes/EmbeddedIndex.cs`
- [Linked index](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/LinkedIndex.cs): `src/Nordmann.LUI/Indexes/LinkedIndex.cs`
- [Index synchronization](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Indexes/EmbeddedSync.cs): `src/Nordmann.LUI/Indexes/EmbeddedSync.cs`

### Query and ranking

- [Query builder](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiQuery.cs): `src/Nordmann.LUI/LuiQuery.cs`
- [Query execution](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/QueryRunner.cs): `src/Nordmann.LUI/Querying/QueryRunner.cs`
- [Candidate reading](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/CandidateReader.cs): `src/Nordmann.LUI/Querying/CandidateReader.cs`
- [Typo correction](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/TypoCorrection.cs): `src/Nordmann.LUI/Querying/TypoCorrection.cs`
- [Ranking and hits](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Querying/Ranker.cs): `src/Nordmann.LUI/Querying/Ranker.cs`
- [Search results](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/LuiResult.cs): `src/Nordmann.LUI/LuiResult.cs`

### SQLite and schema

- [SQLite access](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Storage/Database.cs): `src/Nordmann.LUI/Storage/Database.cs`
- [Embedded schema](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Schema/EmbeddedSource.cs): `src/Nordmann.LUI/Schema/EmbeddedSource.cs`
- [Linked schema](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Schema/LinkedSource.cs): `src/Nordmann.LUI/Schema/LinkedSource.cs`
- [Index definitions](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Schema/IndexDefinition.cs): `src/Nordmann.LUI/Schema/IndexDefinition.cs`

### Normalization and hosting

- [Text normalization](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Normalization/Normalizer.cs): `src/Nordmann.LUI/Normalization/Normalizer.cs`
- [Typo dictionary](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI/Typos/TypoDictionary.cs): `src/Nordmann.LUI/Typos/TypoDictionary.cs`
- [Hosting integration](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI.Hosting/LuiServiceCollectionExtensions.cs): `src/Nordmann.LUI.Hosting/LuiServiceCollectionExtensions.cs`
- [Hosted warmup](https://github.com/nordmanndev/lui/blob/main/src/Nordmann.LUI.Hosting/Hosting/LuiWarmupService.cs): `src/Nordmann.LUI.Hosting/Hosting/LuiWarmupService.cs`

### Other components

- **Application**

## Connections

- Application → Catalog API: opens catalog
- Catalog API → Embedded index: opens index (evidence: `src/Nordmann.LUI/LuiCatalog.cs`)
- Catalog API → Linked index: opens linked (evidence: `src/Nordmann.LUI/LuiCatalog.cs`)
- Application → Query builder: configures search
- Query builder → Embedded index: executes on (evidence: `src/Nordmann.LUI/LuiQuery.cs`)
- Query builder → Linked index: executes on (evidence: `src/Nordmann.LUI/LuiQuery.cs`)
- Embedded index → Query execution: uses runner (evidence: `src/Nordmann.LUI/Indexes/EmbeddedIndex.cs`)
- Linked index → Query execution: uses runner (evidence: `src/Nordmann.LUI/Indexes/LinkedIndex.cs`)
- Query execution → SQLite access: reads SQLite (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Query execution → Candidate reading: reads candidates (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Query execution → Typo correction: requests correction (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Query execution → Ranking and hits: ranks candidates (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Query execution → Typo dictionary: uses dictionary (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Query execution → Search results: returns hits (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Embedded index → Embedded schema: indexes content (evidence: `src/Nordmann.LUI/Indexes/EmbeddedIndex.cs`)
- Linked index → Linked schema: reads linked table (evidence: `src/Nordmann.LUI/Indexes/LinkedIndex.cs`)
- Catalog API → SQLite access: initializes store (evidence: `src/Nordmann.LUI/LuiCatalog.cs`)
- Embedded schema → Index definitions: uses definition (evidence: `src/Nordmann.LUI/Schema/EmbeddedSource.cs`)
- Linked schema → Index definitions: uses definition (evidence: `src/Nordmann.LUI/Schema/LinkedSource.cs`)
- Embedded index → Index synchronization: syncs entries (evidence: `src/Nordmann.LUI/Indexes/EmbeddedIndex.cs`)
- Query execution → Text normalization: normalizes query (evidence: `src/Nordmann.LUI/Querying/QueryRunner.cs`)
- Typo dictionary → Text normalization: normalizes words (evidence: `src/Nordmann.LUI/Typos/TypoDictionary.cs`)
- Application → Hosting integration: registers services (evidence: `src/Nordmann.LUI.Hosting/LuiServiceCollectionExtensions.cs`)
- Hosting integration → Hosted warmup: registers warmup (evidence: `src/Nordmann.LUI.Hosting/LuiServiceCollectionExtensions.cs`)
- Hosted warmup → Catalog API: warms catalog (evidence: `src/Nordmann.LUI.Hosting/Hosting/LuiWarmupService.cs`)