# gitbookio/gitbook architecture

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

- Interactive diagram: https://gitdiagram.com/gitbookio/gitbook
- Repository: https://github.com/gitbookio/gitbook

## Overview

GitBook is a renderer for published technical documentation; the primary journey is a reader opening a published site and viewing its pages. The graph also preserves search, AI assistance, embeds, interactive integrations, OpenAPI rendering, and machine-readable/export routes visible in the repository tree. The README documents the published-content rendering purpose, while source excerpts and the index show selected internal dependencies; unsampled route-to-component wiring is therefore left out rather than inferred.

Main entry points: [`packages/gitbook/src/components/Search/useSearchController.tsx`](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/useSearchController.tsx) (Search Controller), [`packages/gitbook/src/app/sites`](https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites) (Site Routes), [`packages/gitbook/src/components/DocumentView/DocumentView.tsx`](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/DocumentView/DocumentView.tsx) (Document View), [`packages/gitbook/src/components/Search/useSearchResults.ts`](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/useSearchResults.ts) (Search Results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Published Sites"]
  node_site_routes["Site Routes"]
  node_page_renderer["Page Renderer<br/>[page.tsx]"]
  node_site_layout["Site Contexts"]
end

subgraph group_content["Content Rendering"]
  node_document_view["Document View<br/>[DocumentView.tsx]"]
  node_contentkit["ContentKit Blocks"]
  node_openapi["OpenAPI Rendering<br/>[OpenAPIWebhook.tsx]"]
  node_expressions["Expressions<br/>[runtime.ts]"]
end

subgraph group_discovery["Search and AI"]
  node_search_ui["Search Controller"]
  node_search_results["Search Results"]
  node_search_view["Search Display<br/>[SearchResults.tsx]"]
  node_recent_queries["Recent Queries<br/>[recent-queries.ts]"]
  node_rank_fusion["Result Ranking"]
  node_search_api["Search Routes<br/>[route.ts]"]
  node_ai_chat["AI Assistance<br/>[useAIChat.tsx]"]
end

subgraph group_integrations["Embeds and APIs"]
  node_embed_routes["Embed Routes"]
  node_embed_client["Embed Client<br/>[createGitBook.ts]"]
  node_mcp_routes["MCP Routes<br/>[route.ts]"]
  node_exports["Content Exports<br/>[route.ts]"]
end

subgraph group_platform["Site Services"]
  node_site_services["Site Services"]
  node_revalidation["Revalidation<br/>[route.ts]"]
  node_incremental_cache["Incremental Cache"]
end

node_reader(("Reader"))

node_reader -->|"opens published site"| node_site_routes
node_site_routes -.->|"renders pages"| node_page_renderer
node_site_layout -->|"provides search context"| node_search_ui
node_page_renderer -.->|"renders content"| node_document_view
node_document_view -->|"renders integrations"| node_contentkit
node_document_view -.->|"renders API blocks"| node_openapi
node_search_ui -->|"requests results"| node_search_results
node_search_results -->|"records queries"| node_recent_queries
node_search_results -->|"ranks results"| node_rank_fusion
node_search_ui -->|"renders results"| node_search_view
node_search_ui -->|"asks assistant"| node_ai_chat
node_search_ui -.->|"fetches search"| node_search_api
node_reader -.->|"opens embed"| node_embed_routes
node_embed_client -.->|"connects to"| node_embed_routes
node_reader -.->|"uses MCP"| node_mcp_routes
node_reader -.->|"requests exports"| node_exports
node_site_routes -.->|"serves site data"| node_site_services
node_site_services -.->|"accepts revalidation"| node_revalidation
node_site_services -.->|"uses cache"| node_incremental_cache

click node_site_routes "https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites"
click node_page_renderer "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/(content)/%5BpagePath%5D/page.tsx"
click node_site_layout "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/SiteLayout/SiteLayoutClientContexts.tsx"
click node_document_view "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/DocumentView/DocumentView.tsx"
click node_contentkit "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx"
click node_openapi "https://github.com/gitbookio/gitbook/blob/main/packages/react-openapi/src/OpenAPIWebhook.tsx"
click node_expressions "https://github.com/gitbookio/gitbook/blob/main/packages/expr/src/runtime.ts"
click node_search_ui "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/useSearchController.tsx"
click node_search_results "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/useSearchResults.ts"
click node_search_view "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/SearchResults.tsx"
click node_recent_queries "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/recent-queries.ts"
click node_rank_fusion "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/reciprocalRankFusion.ts"
click node_search_api "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/~gitbook/search/route.ts"
click node_ai_chat "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/AI/useAIChat.tsx"
click node_embed_routes "https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/~gitbook/embed"
click node_embed_client "https://github.com/gitbookio/gitbook/blob/main/packages/embed/src/client/createGitBook.ts"
click node_mcp_routes "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/~gitbook/mcp/route.ts"
click node_exports "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/static/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/llms.txt/route.ts"
click node_site_services "https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites"
click node_revalidation "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/~gitbook/revalidate/route.ts"
click node_incremental_cache "https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/openNext/incrementalCache/incrementalCache.ts"

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_site_routes,node_page_renderer,node_site_layout toneBlue
class node_document_view,node_contentkit,node_openapi,node_expressions toneAmber
class node_search_ui,node_search_results,node_search_view,node_recent_queries,node_rank_fusion,node_search_api,node_ai_chat toneMint
class node_embed_routes,node_embed_client,node_mcp_routes,node_exports toneRose
class node_site_services,node_revalidation,node_incremental_cache,node_reader toneIndigo
```

## Components

### Published Sites

- [Site Routes](https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites): `packages/gitbook/src/app/sites`
- [Page Renderer](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/(content)/%5BpagePath%5D/page.tsx): `packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/(content)/[pagePath]/page.tsx`
- [Site Contexts](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/SiteLayout/SiteLayoutClientContexts.tsx): `packages/gitbook/src/components/SiteLayout/SiteLayoutClientContexts.tsx`

### Content Rendering

- [Document View](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/DocumentView/DocumentView.tsx): `packages/gitbook/src/components/DocumentView/DocumentView.tsx`
- [ContentKit Blocks](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx): `packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx`
- [OpenAPI Rendering](https://github.com/gitbookio/gitbook/blob/main/packages/react-openapi/src/OpenAPIWebhook.tsx): `packages/react-openapi/src/OpenAPIWebhook.tsx`
- [Expressions](https://github.com/gitbookio/gitbook/blob/main/packages/expr/src/runtime.ts): `packages/expr/src/runtime.ts`

### Search and AI

- [Search Controller](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/useSearchController.tsx): `packages/gitbook/src/components/Search/useSearchController.tsx`
- [Search Results](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/useSearchResults.ts): `packages/gitbook/src/components/Search/useSearchResults.ts`
- [Search Display](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/SearchResults.tsx): `packages/gitbook/src/components/Search/SearchResults.tsx`
- [Recent Queries](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/recent-queries.ts): `packages/gitbook/src/components/Search/recent-queries.ts`
- [Result Ranking](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/Search/reciprocalRankFusion.ts): `packages/gitbook/src/components/Search/reciprocalRankFusion.ts`
- [Search Routes](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/~gitbook/search/route.ts): `packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/search/route.ts`
- [AI Assistance](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/components/AI/useAIChat.tsx): `packages/gitbook/src/components/AI/useAIChat.tsx`

### Embeds and APIs

- [Embed Routes](https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/~gitbook/embed): `packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/embed`
- [Embed Client](https://github.com/gitbookio/gitbook/blob/main/packages/embed/src/client/createGitBook.ts): `packages/embed/src/client/createGitBook.ts`
- [MCP Routes](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/dynamic/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/~gitbook/mcp/route.ts): `packages/gitbook/src/app/sites/dynamic/[mode]/[siteURL]/[siteData]/~gitbook/mcp/route.ts`
- [Content Exports](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/sites/static/%5Bmode%5D/%5BsiteURL%5D/%5BsiteData%5D/llms.txt/route.ts): `packages/gitbook/src/app/sites/static/[mode]/[siteURL]/[siteData]/llms.txt/route.ts`

### Site Services

- [Site Services](https://github.com/gitbookio/gitbook/tree/main/packages/gitbook/src/app/sites): `packages/gitbook/src/app/sites`
- [Revalidation](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/src/app/~gitbook/revalidate/route.ts): `packages/gitbook/src/app/~gitbook/revalidate/route.ts`
- [Incremental Cache](https://github.com/gitbookio/gitbook/blob/main/packages/gitbook/openNext/incrementalCache/incrementalCache.ts): `packages/gitbook/openNext/incrementalCache/incrementalCache.ts`

### Other components

- **Reader**

## Connections

- Reader → Site Routes: opens published site (evidence: `README.md`)
- Site Routes → Page Renderer: renders pages
- Site Contexts → Search Controller: provides search context (evidence: `packages/gitbook/src/components/SiteLayout/SiteLayoutClientContexts.tsx`)
- Page Renderer → Document View: renders content
- Document View → ContentKit Blocks: renders integrations (evidence: `packages/gitbook/src/components/DocumentView/Integration/ContentKitWithClientContext.tsx`)
- Document View → OpenAPI Rendering: renders API blocks
- Search Controller → Search Results: requests results (evidence: `packages/gitbook/src/components/Search/useSearchController.tsx`)
- Search Results → Recent Queries: records queries (evidence: `packages/gitbook/src/components/Search/useSearchResults.ts`)
- Search Results → Result Ranking: ranks results (evidence: `packages/gitbook/src/components/Search/useSearchResults.ts`)
- Search Controller → Search Display: renders results (evidence: `packages/gitbook/src/components/Search/useSearchController.tsx`)
- Search Controller → AI Assistance: asks assistant (evidence: `packages/gitbook/src/components/Search/useSearchController.tsx`)
- Search Controller → Search Routes: fetches search
- Reader → Embed Routes: opens embed
- Embed Client → Embed Routes: connects to
- Reader → MCP Routes: uses MCP
- Reader → Content Exports: requests exports
- Site Routes → Site Services: serves site data
- Site Services → Revalidation: accepts revalidation
- Site Services → Incremental Cache: uses cache
