# infino-ai/infino architecture

> Architecture diagram of the GitHub repository infino-ai/infino, 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/infino-ai/infino
- Repository: https://github.com/infino-ai/infino

## Overview

Infino is an embedded retrieval library for a single logical table, exposing full-text, vector, hybrid, and SQL queries over Parquet files on local or object storage. The principal workflow is connect, create a table with schema and indexes, append rows, then search or query it. Internally, supertable coordinates immutable-file writing, manifest state, query execution, and caching. README statements establish the end-to-end workflow and storage capabilities; source-index references support several internal relationships, but many implementation files were not sampled, so uncertain call edges are omitted.

Main entry points: [`src/supertable/query/mod.rs`](https://github.com/infino-ai/infino/blob/main/src/supertable/query/mod.rs) (Query Execution), [`src/catalog/mod.rs`](https://github.com/infino-ai/infino/blob/main/src/catalog/mod.rs) (Connection API), [`src/supertable/writer.rs`](https://github.com/infino-ai/infino/blob/main/src/supertable/writer.rs) (Table Writer), [`src/supertable/reader_cache/mod.rs`](https://github.com/infino-ai/infino/blob/main/src/supertable/reader_cache/mod.rs) (Reader Cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Catalog"]
  node_connection["Connection API<br/>[mod.rs]"]
  node_bindings["Language Bindings<br/>[lib.rs]"]
  node_config["Engine Configuration<br/>[mod.rs]"]
end

subgraph group_table["Table Lifecycle"]
  node_schema["Schema and Indexes<br/>[mod.rs]"]
  node_dynamic["Dynamic Rows<br/>[mod.rs]"]
  node_writer["Table Writer<br/>[writer.rs]"]
  node_wal["Write-Ahead Log<br/>[pipeline.rs]"]
  node_manifest[("Table Manifest<br/>[mod.rs]")]
  node_superfile["Parquet Superfiles<br/>[builder.rs]"]
  node_table_handle["Table Handle<br/>[handle.rs]"]
end

subgraph group_retrieval["Retrieval and Query"]
  node_fts["Full-Text Index<br/>[builder.rs]"]
  node_tokenizer["Text Analysis<br/>[tokenize.rs]"]
  node_vector["Vector Index<br/>[hnsw.rs]"]
  node_query["Query Execution<br/>[mod.rs]"]
  node_sql["SQL Planning<br/>[sql.rs]"]
end

subgraph group_persistence["Persistence and Cache"]
  node_storage["Storage Providers<br/>[mod.rs]"]
  node_s3["S3 Backend<br/>[s3.rs]"]
  node_reader_cache["Reader Cache<br/>[mod.rs]"]
  node_block_source["Cached Block Reads<br/>[block_source.rs]"]
  node_memory["Memory Budget<br/>[mod.rs]"]
end

node_app(("Application"))

node_app -->|"connects"| node_connection
node_app -->|"uses"| node_bindings
node_connection -->|"creates tables"| node_schema
node_connection -->|"opens tables"| node_table_handle
node_table_handle -.->|"appends rows"| node_writer
node_writer -->|"writes batches"| node_superfile
node_writer -.->|"records writes"| node_wal
node_writer -.->|"commits files"| node_manifest
node_writer -.->|"accepts JSON rows"| node_dynamic
node_superfile -->|"embeds index"| node_fts
node_superfile -->|"embeds index"| node_vector
node_fts -->|"analyzes text"| node_tokenizer
node_table_handle -.->|"searches table"| node_query
node_query -.->|"plans SQL"| node_sql
node_query -->|"runs full-text search"| node_fts
node_query -->|"runs vector search"| node_vector
node_query -.->|"reads snapshot"| node_manifest
node_query -.->|"loads readers"| node_reader_cache
node_connection -->|"selects storage"| node_storage
node_storage -->|"dispatches backend"| node_s3
node_reader_cache -->|"fetches blocks"| node_block_source
node_reader_cache -->|"reads bytes"| node_storage
node_reader_cache -.->|"budgets residency"| node_memory
node_connection -.->|"loads settings"| node_config

click node_connection "https://github.com/infino-ai/infino/blob/main/src/catalog/mod.rs"
click node_bindings "https://github.com/infino-ai/infino/blob/main/infino-python/src/lib.rs"
click node_schema "https://github.com/infino-ai/infino/blob/main/src/supertable/schema/mod.rs"
click node_dynamic "https://github.com/infino-ai/infino/blob/main/src/dynamic/mod.rs"
click node_writer "https://github.com/infino-ai/infino/blob/main/src/supertable/writer.rs"
click node_wal "https://github.com/infino-ai/infino/blob/main/src/supertable/wal/pipeline.rs"
click node_manifest "https://github.com/infino-ai/infino/blob/main/src/supertable/manifest/mod.rs"
click node_superfile "https://github.com/infino-ai/infino/blob/main/src/superfile/builder.rs"
click node_fts "https://github.com/infino-ai/infino/blob/main/src/superfile/fts/builder.rs"
click node_tokenizer "https://github.com/infino-ai/infino/blob/main/src/superfile/fts/tokenize.rs"
click node_vector "https://github.com/infino-ai/infino/blob/main/src/superfile/vector/hnsw.rs"
click node_query "https://github.com/infino-ai/infino/blob/main/src/supertable/query/mod.rs"
click node_sql "https://github.com/infino-ai/infino/blob/main/src/supertable/query/sql.rs"
click node_table_handle "https://github.com/infino-ai/infino/blob/main/src/supertable/handle.rs"
click node_storage "https://github.com/infino-ai/infino/blob/main/src/storage/mod.rs"
click node_s3 "https://github.com/infino-ai/infino/blob/main/src/storage/s3.rs"
click node_reader_cache "https://github.com/infino-ai/infino/blob/main/src/supertable/reader_cache/mod.rs"
click node_block_source "https://github.com/infino-ai/infino/blob/main/src/supertable/reader_cache/block_source.rs"
click node_memory "https://github.com/infino-ai/infino/blob/main/src/memory/mod.rs"
click node_config "https://github.com/infino-ai/infino/blob/main/src/config/mod.rs"

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_connection,node_bindings,node_config toneBlue
class node_schema,node_dynamic,node_writer,node_wal,node_manifest,node_superfile,node_table_handle toneAmber
class node_fts,node_tokenizer,node_vector,node_query,node_sql toneMint
class node_storage,node_s3,node_reader_cache,node_block_source,node_memory toneRose
class node_app toneIndigo
```

## Components

### API and Catalog

- [Connection API](https://github.com/infino-ai/infino/blob/main/src/catalog/mod.rs): `src/catalog/mod.rs`
- [Language Bindings](https://github.com/infino-ai/infino/blob/main/infino-python/src/lib.rs): `infino-python/src/lib.rs`
- [Engine Configuration](https://github.com/infino-ai/infino/blob/main/src/config/mod.rs): `src/config/mod.rs`

### Table Lifecycle

- [Schema and Indexes](https://github.com/infino-ai/infino/blob/main/src/supertable/schema/mod.rs): `src/supertable/schema/mod.rs`
- [Dynamic Rows](https://github.com/infino-ai/infino/blob/main/src/dynamic/mod.rs): `src/dynamic/mod.rs`
- [Table Writer](https://github.com/infino-ai/infino/blob/main/src/supertable/writer.rs): `src/supertable/writer.rs`
- [Write-Ahead Log](https://github.com/infino-ai/infino/blob/main/src/supertable/wal/pipeline.rs): `src/supertable/wal/pipeline.rs`
- [Table Manifest](https://github.com/infino-ai/infino/blob/main/src/supertable/manifest/mod.rs): `src/supertable/manifest/mod.rs`
- [Parquet Superfiles](https://github.com/infino-ai/infino/blob/main/src/superfile/builder.rs): `src/superfile/builder.rs`
- [Table Handle](https://github.com/infino-ai/infino/blob/main/src/supertable/handle.rs): `src/supertable/handle.rs`

### Retrieval and Query

- [Full-Text Index](https://github.com/infino-ai/infino/blob/main/src/superfile/fts/builder.rs): `src/superfile/fts/builder.rs`
- [Text Analysis](https://github.com/infino-ai/infino/blob/main/src/superfile/fts/tokenize.rs): `src/superfile/fts/tokenize.rs`
- [Vector Index](https://github.com/infino-ai/infino/blob/main/src/superfile/vector/hnsw.rs): `src/superfile/vector/hnsw.rs`
- [Query Execution](https://github.com/infino-ai/infino/blob/main/src/supertable/query/mod.rs): `src/supertable/query/mod.rs`
- [SQL Planning](https://github.com/infino-ai/infino/blob/main/src/supertable/query/sql.rs): `src/supertable/query/sql.rs`

### Persistence and Cache

- [Storage Providers](https://github.com/infino-ai/infino/blob/main/src/storage/mod.rs): `src/storage/mod.rs`
- [S3 Backend](https://github.com/infino-ai/infino/blob/main/src/storage/s3.rs): `src/storage/s3.rs`
- [Reader Cache](https://github.com/infino-ai/infino/blob/main/src/supertable/reader_cache/mod.rs): `src/supertable/reader_cache/mod.rs`
- [Cached Block Reads](https://github.com/infino-ai/infino/blob/main/src/supertable/reader_cache/block_source.rs): `src/supertable/reader_cache/block_source.rs`
- [Memory Budget](https://github.com/infino-ai/infino/blob/main/src/memory/mod.rs): `src/memory/mod.rs`

### Other components

- **Application**

## Connections

- Application → Connection API: connects (evidence: `README.md`)
- Application → Language Bindings: uses (evidence: `README.md`)
- Connection API → Schema and Indexes: creates tables (evidence: `README.md`)
- Connection API → Table Handle: opens tables (evidence: `src/catalog/mod.rs`)
- Table Handle → Table Writer: appends rows
- Table Writer → Parquet Superfiles: writes batches (evidence: `README.md`)
- Table Writer → Write-Ahead Log: records writes
- Table Writer → Table Manifest: commits files
- Table Writer → Dynamic Rows: accepts JSON rows
- Parquet Superfiles → Full-Text Index: embeds index (evidence: `README.md`)
- Parquet Superfiles → Vector Index: embeds index (evidence: `README.md`)
- Full-Text Index → Text Analysis: analyzes text (evidence: `src/superfile/fts/builder.rs`)
- Table Handle → Query Execution: searches table
- Query Execution → SQL Planning: plans SQL
- Query Execution → Full-Text Index: runs full-text search (evidence: `README.md`)
- Query Execution → Vector Index: runs vector search (evidence: `README.md`)
- Query Execution → Table Manifest: reads snapshot
- Query Execution → Reader Cache: loads readers
- Connection API → Storage Providers: selects storage (evidence: `README.md`)
- Storage Providers → S3 Backend: dispatches backend (evidence: `src/storage/mod.rs`)
- Reader Cache → Cached Block Reads: fetches blocks (evidence: `src/supertable/reader_cache/mod.rs`)
- Reader Cache → Storage Providers: reads bytes (evidence: `src/supertable/reader_cache/mod.rs`)
- Reader Cache → Memory Budget: budgets residency
- Connection API → Engine Configuration: loads settings