# lancedb/docs architecture

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

- Interactive diagram: https://gitdiagram.com/lancedb/docs
- Repository: https://github.com/lancedb/docs

## Overview

1. This repository is a documentation site, not the product runtime itself. The center of gravity is `docs/`, which contains Mintlify-authored MDX pages, site configuration, static assets, and generated content for LanceDB topics.

2. The docs are organized by product surface area: quickstart, tables, storage, indexing, search, reranking, embeddings, integrations, enterprise, Geneva, API reference, tutorials, and datasets. These sections map directly to the navigation defined in `docs/docs.json`.

3. `docs/docs.json` is the top-level site/navigation boundary. Mintlify uses it to build the sidebar and page structure, while `docs/static/` provides images, CSS, and other assets referenced from the pages.

4. A major architectural pattern is “tested code snippets as documentation.” The language-specific example suites in `tests/py`, `tests/ts`, and `tests/rs` are the source of truth for code blocks. `scripts/mdx_snippets_gen.py` converts those tested snippets into MDX under `docs/snippets/`, and the Makefile exposes this as `make py`, `make ts`, `make rs`, or `make snippets`.

5. The snippet pipeline is intentionally one-way: tests validate the examples, then generated MDX is imported into pages via `<CodeBlock>`-style usage. This keeps docs examples aligned with working Python, TypeScript, and Rust APIs rather than hand-maintained prose snippets.

6. Dataset documentation is another generated subsystem. `scripts/sync_hf_datasets.py` reads `scripts/hf_datasets.yaml`, fetches upstream `HF_DATASET_CARD.md` files from the `lance-format/lance-huggingface` GitHub repo, rewrites them into Mintlify-compatible MDX, updates `docs/datasets/*.mdx`, refreshes `docs/datasets/index.mdx`, and keeps the `Datasets` sidebar section in sync.

7. The API reference is handled separately under `docs/api-reference/`, with the REST schema stored in `docs/api-reference/rest/openapi.yml`. A GitHub Actions workflow (`.github/workflows/sync-openapi.yml`) keeps that spec synchronized, so the reference docs remain tied to the current API contract.

8. CI and automation live in `.github/workflows/`. `docs-ci.yml` is the main documentation validation pipeline, covering site correctness and likely link/content checks. These workflows are the release boundary for changes to docs content and generated artifacts.

9. The repo also contains a dedicated documentation-audit workflow under `workflows/docs-audit/`. That is a separate Python toolchain with its own config, prompts, manifests, parser, visibility logic, and tests. It appears to run periodic audits of documentation coverage/quality, including enterprise-specific gap detection, and uses OpenAI plus an internal enterprise store abstraction.

10. Tutorials under `docs/tutorials/` are a second-order content layer: they mix narrative docs with runnable example code and sometimes companion files like `config.py`, `main.py`, and `requirements.txt`. These are closer to end-to-end recipes than reference pages.

11. The `skills/` and `workflows/docs-audit/skills/` directories contain authoring guidance for automation and AI-assisted workflows. They are not runtime code paths, but they shape how docs are generated, reviewed, and audited.

12. In architecture-diagram terms, the repository has three main flows: authoring flow from MDX/editable content into Mintlify; generation flow from tests/upstream sources into `docs/snippets/` and `docs/datasets/`; and validation/automation flow through GitHub Actions and the docs-audit toolchain. The boundaries are clear: source content, generated docs, and CI/audit automation.

Main entry points: [`docs/docs.json`](https://github.com/lancedb/docs/blob/main/docs/docs.json) (Sidebar), [`.github/workflows/docs-ci.yml`](https://github.com/lancedb/docs/blob/main/.github/workflows/docs-ci.yml) (Docs CI), [`docs/snippets`](https://github.com/lancedb/docs/tree/main/docs/snippets) (Snippets), [`workflows/docs-audit`](https://github.com/lancedb/docs/tree/main/workflows/docs-audit) (Docs audit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs_site["Docs site"]
  node_docs_index["Home<br/>landing mdx<br/>[index.mdx]"]
  node_docs_nav["Sidebar<br/>site config<br/>[docs.json]"]
  node_docs_static[("Static assets")]
  node_quickstart["Quickstart<br/>product docs<br/>[quickstart.mdx]"]
  node_tables_docs["Tables<br/>product docs"]
  node_storage_docs["Storage<br/>product docs"]
  node_indexing_docs["Indexing<br/>product docs"]
  node_search_docs["Search<br/>product docs"]
  node_reranking_docs["Reranking<br/>product docs"]
  node_embedding_docs["Embeddings<br/>product docs"]
  node_integrations_docs["Integrations<br/>ecosystem docs"]
  node_enterprise_docs["Enterprise"]
  node_geneva_docs["Geneva<br/>runtime docs"]
  node_api_docs["API reference<br/>reference docs"]
  node_tutorials_docs["Tutorials<br/>recipes"]
  node_openapi_spec["OpenAPI spec<br/>api schema<br/>[openapi.yml]"]
end

subgraph group_generated["Generated content"]
  node_datasets_docs["Datasets<br/>generated docs"]
  node_snippets_docs["Snippets<br/>generated mdx"]
  node_snippet_tests["Example tests<br/>language suites"]
  node_snippet_gen["Snippet generator<br/>script"]
  node_dataset_sync["Dataset sync<br/>sync script"]
  node_hf_config["HF config<br/>dataset manifest<br/>[hf_datasets.yaml]"]
end

subgraph group_automation["Automation"]
  node_docs_ci["Docs CI<br/>github actions<br/>[docs-ci.yml]"]
  node_openapi_sync["OpenAPI sync<br/>github actions<br/>[sync-openapi.yml]"]
  node_docs_audit["Docs audit<br/>python toolchain"]
end

subgraph group_guidance["Authoring guidance"]
  node_authoring_guidance["Writing guide<br/>authoring guidance<br/>[WRITING.md]"]
  node_docs_writer_skill["Docs writer<br/>skill<br/>[SKILL.md]"]
  node_audit_skills["Audit skills<br/>skill set"]
end

node_docs_nav -->|"navigates"| node_docs_index
node_docs_nav -->|"indexes"| node_quickstart
node_docs_nav -->|"indexes"| node_tables_docs
node_docs_nav -->|"indexes"| node_storage_docs
node_docs_nav -->|"indexes"| node_indexing_docs
node_docs_nav -->|"indexes"| node_search_docs
node_docs_nav -->|"indexes"| node_reranking_docs
node_docs_nav -->|"indexes"| node_embedding_docs
node_docs_nav -->|"indexes"| node_integrations_docs
node_docs_nav -->|"indexes"| node_enterprise_docs
node_docs_nav -->|"indexes"| node_geneva_docs
node_docs_nav -->|"indexes"| node_api_docs
node_docs_nav -->|"indexes"| node_tutorials_docs
node_docs_nav -->|"indexes"| node_datasets_docs
node_docs_index -->|"uses"| node_docs_static
node_snippet_tests -->|"validates"| node_snippet_gen
node_snippet_gen -->|"writes"| node_snippets_docs
node_quickstart -->|"imports"| node_snippets_docs
node_tables_docs -->|"imports"| node_snippets_docs
node_search_docs -->|"imports"| node_snippets_docs
node_geneva_docs -->|"imports"| node_snippets_docs
node_dataset_sync -->|"reads"| node_hf_config
node_dataset_sync -->|"writes"| node_datasets_docs
node_openapi_sync -->|"updates"| node_openapi_spec
node_openapi_spec -->|"drives"| node_api_docs
node_docs_ci -->|"validates"| node_docs_nav
node_docs_ci -->|"validates"| node_snippets_docs
node_docs_ci -->|"validates"| node_datasets_docs
node_docs_ci -->|"validates"| node_openapi_spec
node_docs_ci -->|"validates"| node_docs_static
node_docs_audit -.->|"audits"| node_docs_index
node_docs_audit -.->|"focuses"| node_enterprise_docs
node_authoring_guidance -->|"guides"| node_docs_writer_skill
node_docs_writer_skill -.->|"supports"| node_docs_ci
node_audit_skills -.->|"supports"| node_docs_audit

click node_docs_index "https://github.com/lancedb/docs/blob/main/docs/index.mdx"
click node_docs_nav "https://github.com/lancedb/docs/blob/main/docs/docs.json"
click node_docs_static "https://github.com/lancedb/docs/tree/main/docs/static"
click node_quickstart "https://github.com/lancedb/docs/blob/main/docs/quickstart.mdx"
click node_tables_docs "https://github.com/lancedb/docs/tree/main/docs/tables"
click node_storage_docs "https://github.com/lancedb/docs/tree/main/docs/storage"
click node_indexing_docs "https://github.com/lancedb/docs/tree/main/docs/indexing"
click node_search_docs "https://github.com/lancedb/docs/tree/main/docs/search"
click node_reranking_docs "https://github.com/lancedb/docs/tree/main/docs/reranking"
click node_embedding_docs "https://github.com/lancedb/docs/tree/main/docs/embedding"
click node_integrations_docs "https://github.com/lancedb/docs/tree/main/docs/integrations"
click node_enterprise_docs "https://github.com/lancedb/docs/tree/main/docs/enterprise"
click node_geneva_docs "https://github.com/lancedb/docs/tree/main/docs/geneva"
click node_api_docs "https://github.com/lancedb/docs/tree/main/docs/api-reference"
click node_tutorials_docs "https://github.com/lancedb/docs/tree/main/docs/tutorials"
click node_datasets_docs "https://github.com/lancedb/docs/tree/main/docs/datasets"
click node_snippets_docs "https://github.com/lancedb/docs/tree/main/docs/snippets"
click node_snippet_tests "https://github.com/lancedb/docs/tree/main/tests"
click node_snippet_gen "https://github.com/lancedb/docs/blob/main/scripts/mdx_snippets_gen.py"
click node_dataset_sync "https://github.com/lancedb/docs/blob/main/scripts/sync_hf_datasets.py"
click node_hf_config "https://github.com/lancedb/docs/blob/main/scripts/hf_datasets.yaml"
click node_openapi_spec "https://github.com/lancedb/docs/blob/main/docs/api-reference/rest/openapi.yml"
click node_docs_ci "https://github.com/lancedb/docs/blob/main/.github/workflows/docs-ci.yml"
click node_openapi_sync "https://github.com/lancedb/docs/blob/main/.github/workflows/sync-openapi.yml"
click node_docs_audit "https://github.com/lancedb/docs/tree/main/workflows/docs-audit"
click node_authoring_guidance "https://github.com/lancedb/docs/blob/main/WRITING.md"
click node_docs_writer_skill "https://github.com/lancedb/docs/blob/main/skills/docs-writer/SKILL.md"
click node_audit_skills "https://github.com/lancedb/docs/tree/main/workflows/docs-audit/skills"

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_docs_index,node_docs_nav,node_docs_static,node_quickstart,node_tables_docs,node_storage_docs,node_indexing_docs,node_search_docs,node_reranking_docs,node_embedding_docs,node_integrations_docs,node_enterprise_docs,node_geneva_docs,node_api_docs,node_tutorials_docs,node_openapi_spec toneBlue
class node_datasets_docs,node_snippets_docs,node_snippet_tests,node_snippet_gen,node_dataset_sync,node_hf_config toneAmber
class node_docs_ci,node_openapi_sync,node_docs_audit toneMint
class node_authoring_guidance,node_docs_writer_skill,node_audit_skills toneRose
```

## Components

### Docs site

Mintlify-authored documentation content and site structure.

- [Home](https://github.com/lancedb/docs/blob/main/docs/index.mdx): landing mdx · Top-level documentation entry point and overview page. · `docs/index.mdx`
- [Sidebar](https://github.com/lancedb/docs/blob/main/docs/docs.json): site config · Mintlify navigation and page structure boundary. · `docs/docs.json`
- [Static assets](https://github.com/lancedb/docs/tree/main/docs/static): assets · Images, styles, and other shared site assets. · `docs/static`
- [Quickstart](https://github.com/lancedb/docs/blob/main/docs/quickstart.mdx): product docs · Getting-started content for the core product surface. · `docs/quickstart.mdx`
- [Tables](https://github.com/lancedb/docs/tree/main/docs/tables): product docs · Table creation, schema, updates, consistency, and versioning docs. · `docs/tables`
- [Storage](https://github.com/lancedb/docs/tree/main/docs/storage): product docs · Storage configuration and persistence documentation. · `docs/storage`
- [Indexing](https://github.com/lancedb/docs/tree/main/docs/indexing): product docs · Vector, scalar, full-text, GPU, quantization, and reindexing docs. · `docs/indexing`
- [Search](https://github.com/lancedb/docs/tree/main/docs/search): product docs · Filtering, vector, full-text, hybrid, SQL, and multivector search docs. · `docs/search`
- [Reranking](https://github.com/lancedb/docs/tree/main/docs/reranking): product docs · Reranking strategies, evaluation, and combination methods. · `docs/reranking`
- [Embeddings](https://github.com/lancedb/docs/tree/main/docs/embedding): product docs · Embedding quickstart and embedding-specific guidance. · `docs/embedding`
- [Integrations](https://github.com/lancedb/docs/tree/main/docs/integrations): ecosystem docs · Third-party AI, data, embedding, and reranking integrations. · `docs/integrations`
- [Enterprise](https://github.com/lancedb/docs/tree/main/docs/enterprise): enterprise docs · Enterprise architecture, deployment, benchmarks, and security. · `docs/enterprise`
- [Geneva](https://github.com/lancedb/docs/tree/main/docs/geneva): runtime docs · Geneva deployment, jobs, UDFs, and operational reference. · `docs/geneva`
- [API reference](https://github.com/lancedb/docs/tree/main/docs/api-reference): reference docs · API reference landing area for product contracts. · `docs/api-reference`
- [Tutorials](https://github.com/lancedb/docs/tree/main/docs/tutorials): recipes · End-to-end tutorials and applied workflows. · `docs/tutorials`
- [OpenAPI spec](https://github.com/lancedb/docs/blob/main/docs/api-reference/rest/openapi.yml): api schema · REST API contract used by the reference docs. · `docs/api-reference/rest/openapi.yml`

### Generated content

Docs artifacts produced from tested examples and upstream sources.

- [Datasets](https://github.com/lancedb/docs/tree/main/docs/datasets): generated docs · Generated dataset pages synced from upstream dataset cards. · `docs/datasets`
- [Snippets](https://github.com/lancedb/docs/tree/main/docs/snippets): generated mdx · Generated tested code snippets imported into MDX pages. · `docs/snippets`
- [Example tests](https://github.com/lancedb/docs/tree/main/tests): language suites · Python, TypeScript, and Rust snippet source-of-truth test suites. · `tests`
- [Snippet generator](https://github.com/lancedb/docs/blob/main/scripts/mdx_snippets_gen.py): script · Converts tested examples into reusable MDX snippet blocks. · `scripts/mdx_snippets_gen.py`
- [Dataset sync](https://github.com/lancedb/docs/blob/main/scripts/sync_hf_datasets.py): sync script · Fetches upstream dataset cards and rewrites them into Mintlify MDX. · `scripts/sync_hf_datasets.py`
- [HF config](https://github.com/lancedb/docs/blob/main/scripts/hf_datasets.yaml): dataset manifest · Dataset source list used by the sync pipeline. · `scripts/hf_datasets.yaml`

### Automation

CI, sync jobs, and audit tooling that validate or refresh docs.

- [Docs CI](https://github.com/lancedb/docs/blob/main/.github/workflows/docs-ci.yml): github actions · Primary documentation validation workflow. · `.github/workflows/docs-ci.yml`
- [OpenAPI sync](https://github.com/lancedb/docs/blob/main/.github/workflows/sync-openapi.yml): github actions · Workflow that keeps the REST schema synchronized. · `.github/workflows/sync-openapi.yml`
- [Docs audit](https://github.com/lancedb/docs/tree/main/workflows/docs-audit): python toolchain · Independent docs quality and coverage audit system. · `workflows/docs-audit`

### Authoring guidance

Human and AI authoring instructions that shape documentation workflows.

- [Writing guide](https://github.com/lancedb/docs/blob/main/WRITING.md): authoring guidance · Documentation writing and automation guidance for contributors. · `WRITING.md`
- [Docs writer](https://github.com/lancedb/docs/blob/main/skills/docs-writer/SKILL.md): skill · Authoring guidance for docs generation and review workflows. · `skills/docs-writer/SKILL.md`
- [Audit skills](https://github.com/lancedb/docs/tree/main/workflows/docs-audit/skills): skill set · Specialized skills for docs-audit enterprise summaries and manifest authoring. · `workflows/docs-audit/skills`

## Connections

- Sidebar → Home: navigates · Sidebar structure points users to the docs landing page.
- Sidebar → Quickstart: indexes · Navigation defines the quickstart section.
- Sidebar → Tables: indexes · Navigation defines the tables section.
- Sidebar → Storage: indexes · Navigation defines the storage section.
- Sidebar → Indexing: indexes · Navigation defines the indexing section.
- Sidebar → Search: indexes · Navigation defines the search section.
- Sidebar → Reranking: indexes · Navigation defines the reranking section.
- Sidebar → Embeddings: indexes · Navigation defines the embeddings section.
- Sidebar → Integrations: indexes · Navigation defines the integrations section.
- Sidebar → Enterprise: indexes · Navigation defines the enterprise section.
- Sidebar → Geneva: indexes · Navigation defines the Geneva section.
- Sidebar → API reference: indexes · Navigation defines the API reference area.
- Sidebar → Tutorials: indexes · Navigation defines the tutorials section.
- Sidebar → Datasets: indexes · Navigation defines the datasets section.
- Home → Static assets: uses · Landing pages and components rely on shared assets and styles.
- Example tests → Snippet generator: validates · Tested examples are the source of truth for generated snippets.
- Snippet generator → Snippets: writes · Generator emits MDX snippets used by documentation pages.
- Quickstart → Snippets: imports · Quickstart content consumes generated code examples.
- Tables → Snippets: imports · Table docs consume generated examples.
- Search → Snippets: imports · Search docs consume generated examples.
- Geneva → Snippets: imports · Geneva docs consume generated examples.
- Dataset sync → HF config: reads · Sync job is driven by the upstream dataset manifest.
- Dataset sync → Datasets: writes · Sync job regenerates dataset pages and index content.
- OpenAPI sync → OpenAPI spec: updates · Workflow keeps the REST schema current.
- OpenAPI spec → API reference: drives · OpenAPI contract underpins the API reference pages.
- Docs CI → Sidebar: validates · Documentation CI checks the site structure boundary.
- Docs CI → Snippets: validates · CI verifies generated snippets and docs content.
- Docs CI → Datasets: validates · CI verifies generated dataset docs.
- Docs CI → OpenAPI spec: validates · CI checks the API reference contract artifacts.
- Docs CI → Static assets: validates · CI checks site assets used by the docs.
- Docs audit → Home: audits · Separate toolchain audits documentation quality and coverage.
- Docs audit → Enterprise: focuses · Audit tooling includes enterprise-specific coverage checks.
- Writing guide → Docs writer: guides · Repo writing guidance supports docs authoring workflows.
- Docs writer → Docs CI: supports · Authoring guidance is shaped around validation constraints.
- Audit skills → Docs audit: supports · Skills package supports the audit toolchain and summaries.