# bookstackapp/bookstack architecture

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

- Interactive diagram: https://gitdiagram.com/bookstackapp/bookstack
- Repository: https://github.com/bookstackapp/bookstack

## Overview

BookStack is a documentation platform for organizing books, chapters, and pages. A typical workflow is: a user authenticates, requests a page, the page controller loads and renders entity content, and the browser receives the result. Content management is governed by permissions and can include comments, activity tracking, uploads, search, exports, API access, and theming. The graph preserves these major capabilities; several subsystem relationships are inferred only from the tree because their implementations were not sampled.

Main entry points: [`app/Entities/Controllers/PageController.php`](https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Controllers/PageController.php) (Page Controller), [`app/Entities/Models/Entity.php`](https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Models/Entity.php) (Entity Models), [`app/Access/Controllers/LoginController.php`](https://github.com/bookstackapp/bookstack/blob/development/app/Access/Controllers/LoginController.php) (Login Controller), [`app/Search/SearchController.php`](https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchController.php) (Search Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access Control"]
  node_login["Login Controller"]
  node_login_service["Login Service<br/>[LoginService.php]"]
  node_mfa["MFA Controllers<br/>[MfaController.php]"]
  node_social_auth["Social Authentication"]
end

subgraph group_content["Documentation Content"]
  node_page_controller["Page Controller<br/>[PageController.php]"]
  node_entity_models["Entity Models<br/>[Entity.php]"]
  node_page_content["Page Content<br/>[PageContent.php]"]
  node_permissions["Permission Controller"]
end

subgraph group_platform["Platform Services"]
  node_database[("Application Database<br/>[database.php]")]
  node_search_controller["Search Controller"]
  node_search_runner["Search Runner<br/>[SearchRunner.php]"]
  node_search_index[("Search Index<br/>[SearchIndex.php]")]
  node_activity["Activity Logging<br/>[ActivityLogger.php]"]
  node_uploads["Image Storage<br/>[ImageStorage.php]"]
  node_file_store[("File Storage")]
end

subgraph group_extensions["Integrations"]
  node_api["API Tokens"]
  node_exports["Import Export"]
  node_theme["Theme Modules"]
end

node_user(("User"))
node_identity_providers{{"Identity Providers"}}
node_response["Web Response<br/>[Controller.php]"]

node_user -->|"submits login"| node_login
node_login -->|"authenticates"| node_login_service
node_login -->|"dispatches MFA"| node_mfa
node_user -.->|"starts sign-in"| node_social_auth
node_social_auth -.->|"uses provider"| node_identity_providers
node_user -->|"requests page"| node_page_controller
node_page_controller -->|"loads entity"| node_entity_models
node_page_controller -->|"renders content"| node_page_content
node_page_controller -->|"returns view"| node_response
node_page_controller -->|"records views"| node_activity
node_permissions -->|"updates access"| node_entity_models
node_entity_models -->|"reads writes"| node_database
node_user -->|"searches content"| node_search_controller
node_search_controller -->|"runs search"| node_search_runner
node_search_runner -->|"queries index"| node_search_index
node_search_controller -->|"returns results"| node_response
node_page_controller -->|"handles images"| node_uploads
node_uploads -->|"stores files"| node_file_store
node_api -->|"stores tokens"| node_database
node_exports -->|"exports entities"| node_entity_models
node_theme -.->|"customizes views"| node_response

click node_login "https://github.com/bookstackapp/bookstack/blob/development/app/Access/Controllers/LoginController.php"
click node_login_service "https://github.com/bookstackapp/bookstack/blob/development/app/Access/LoginService.php"
click node_mfa "https://github.com/bookstackapp/bookstack/blob/development/app/Access/Controllers/MfaController.php"
click node_social_auth "https://github.com/bookstackapp/bookstack/blob/development/app/Access/SocialAuthService.php"
click node_page_controller "https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Controllers/PageController.php"
click node_entity_models "https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Models/Entity.php"
click node_page_content "https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Tools/PageContent.php"
click node_permissions "https://github.com/bookstackapp/bookstack/blob/development/app/Permissions/PermissionsController.php"
click node_database "https://github.com/bookstackapp/bookstack/blob/development/app/Config/database.php"
click node_search_controller "https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchController.php"
click node_search_runner "https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchRunner.php"
click node_search_index "https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchIndex.php"
click node_activity "https://github.com/bookstackapp/bookstack/blob/development/app/Activity/Tools/ActivityLogger.php"
click node_uploads "https://github.com/bookstackapp/bookstack/blob/development/app/Uploads/ImageStorage.php"
click node_file_store "https://github.com/bookstackapp/bookstack/blob/development/app/Uploads/ImageStorageDisk.php"
click node_api "https://github.com/bookstackapp/bookstack/blob/development/app/Api/UserApiTokenController.php"
click node_exports "https://github.com/bookstackapp/bookstack/blob/development/app/Exports/ExportFormatter.php"
click node_theme "https://github.com/bookstackapp/bookstack/blob/development/app/Theming/ThemeModuleManager.php"
click node_response "https://github.com/bookstackapp/bookstack/blob/development/app/Http/Controller.php"

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_login,node_login_service,node_mfa,node_social_auth,node_user toneBlue
class node_page_controller,node_entity_models,node_page_content,node_permissions toneAmber
class node_database,node_search_controller,node_search_runner,node_search_index,node_activity,node_uploads,node_file_store toneMint
class node_api,node_exports,node_theme toneRose
class node_identity_providers toneIndigo
class node_response toneTeal
```

## Components

### Access Control

- [Login Controller](https://github.com/bookstackapp/bookstack/blob/development/app/Access/Controllers/LoginController.php): `app/Access/Controllers/LoginController.php`
- [Login Service](https://github.com/bookstackapp/bookstack/blob/development/app/Access/LoginService.php): `app/Access/LoginService.php`
- [MFA Controllers](https://github.com/bookstackapp/bookstack/blob/development/app/Access/Controllers/MfaController.php): `app/Access/Controllers/MfaController.php`
- [Social Authentication](https://github.com/bookstackapp/bookstack/blob/development/app/Access/SocialAuthService.php): `app/Access/SocialAuthService.php`

### Documentation Content

- [Page Controller](https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Controllers/PageController.php): `app/Entities/Controllers/PageController.php`
- [Entity Models](https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Models/Entity.php): `app/Entities/Models/Entity.php`
- [Page Content](https://github.com/bookstackapp/bookstack/blob/development/app/Entities/Tools/PageContent.php): `app/Entities/Tools/PageContent.php`
- [Permission Controller](https://github.com/bookstackapp/bookstack/blob/development/app/Permissions/PermissionsController.php): `app/Permissions/PermissionsController.php`

### Platform Services

- [Application Database](https://github.com/bookstackapp/bookstack/blob/development/app/Config/database.php): `app/Config/database.php`
- [Search Controller](https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchController.php): `app/Search/SearchController.php`
- [Search Runner](https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchRunner.php): `app/Search/SearchRunner.php`
- [Search Index](https://github.com/bookstackapp/bookstack/blob/development/app/Search/SearchIndex.php): `app/Search/SearchIndex.php`
- [Activity Logging](https://github.com/bookstackapp/bookstack/blob/development/app/Activity/Tools/ActivityLogger.php): `app/Activity/Tools/ActivityLogger.php`
- [Image Storage](https://github.com/bookstackapp/bookstack/blob/development/app/Uploads/ImageStorage.php): `app/Uploads/ImageStorage.php`
- [File Storage](https://github.com/bookstackapp/bookstack/blob/development/app/Uploads/ImageStorageDisk.php): `app/Uploads/ImageStorageDisk.php`

### Integrations

- [API Tokens](https://github.com/bookstackapp/bookstack/blob/development/app/Api/UserApiTokenController.php): `app/Api/UserApiTokenController.php`
- [Import Export](https://github.com/bookstackapp/bookstack/blob/development/app/Exports/ExportFormatter.php): `app/Exports/ExportFormatter.php`
- [Theme Modules](https://github.com/bookstackapp/bookstack/blob/development/app/Theming/ThemeModuleManager.php): `app/Theming/ThemeModuleManager.php`

### Other components

- **User**
- **Identity Providers**
- [Web Response](https://github.com/bookstackapp/bookstack/blob/development/app/Http/Controller.php): `app/Http/Controller.php`

## Connections

- User → Login Controller: submits login
- Login Controller → Login Service: authenticates
- Login Controller → MFA Controllers: dispatches MFA
- User → Social Authentication: starts sign-in
- Social Authentication → Identity Providers: uses provider
- User → Page Controller: requests page
- Page Controller → Entity Models: loads entity
- Page Controller → Page Content: renders content
- Page Controller → Web Response: returns view
- Page Controller → Activity Logging: records views
- Permission Controller → Entity Models: updates access
- Entity Models → Application Database: reads writes
- User → Search Controller: searches content
- Search Controller → Search Runner: runs search
- Search Runner → Search Index: queries index
- Search Controller → Web Response: returns results
- Page Controller → Image Storage: handles images
- Image Storage → File Storage: stores files
- API Tokens → Application Database: stores tokens
- Import Export → Entity Models: exports entities
- Theme Modules → Web Response: customizes views
