# pocketbase/pocketbase architecture

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

- Interactive diagram: https://gitdiagram.com/pocketbase/pocketbase
- Repository: https://github.com/pocketbase/pocketbase

## Overview

#### Purpose and Entry Points
PocketBase is a Go-embeddable, single-binary backend: SQLite persistence, REST-style APIs, auth, file storage, realtime subscriptions, and an embedded admin UI. Library construction begins at `pocketbase.go`; applications commonly instantiate it and call `Start()`. The standalone example is `examples/base/main.go`; CLI commands, including serving and superuser administration, are in `cmd/serve.go` and `cmd/superuser.go`.

#### Application Lifecycle and Extension Boundary
`core/app.go` owns the application runtime and services. Its event system in `core/events.go` exposes lifecycle/request hooks used by Go applications and plugins; request context is modeled through `core/event_request.go`. The JavaScript extension runtime is a distinct plugin boundary: `plugins/jsvm/jsvm.go` and `plugins/jsvm/binds.go` host/bind application capabilities, while `plugins/jsvm/pool.go` manages VM execution resources.

#### HTTP API, Routing, and Realtime
The serving layer registers API endpoints and middleware in `apis/serve.go` and `apis/middlewares.go`, on the custom router abstraction in `tools/router/router.go`. Domain endpoints split into record CRUD (`apis/record_crud.go`), authentication (`apis/record_auth.go`), and operational endpoints such as backup/settings. Realtime connections are handled in `apis/realtime.go` and backed by in-process subscription primitives in `tools/subscriptions/broker.go`; record/activity changes can therefore fan out to connected clients without an external message broker.

#### Data Model, Persistence, and Querying
The core data boundary is dynamically defined collections, fields, and records: `core/collection_model.go`, `core/field.go`, and `core/record_model.go`. Collection definitions determine record-table synchronization (`core/collection_record_table_sync.go`) and validation (`core/collection_validate.go`). Database lifecycle, connections, and transactions reside in `core/db.go`, `core/db_connect.go`, and `core/db_tx.go`; the documented embedded engine is SQLite, with pure-Go/static-build support. Record querying/expansion is centralized in `core/record_query.go` and `core/record_query_expand.go`.

#### Security and Identity Flows
Authentication supports password, OTP, OAuth2, refresh tokens, MFA, email verification/change, password reset, impersonation, and superusers. The public HTTP flow is implemented across `apis/record_auth_with_password.go`, `apis/record_auth_with_oauth2.go`, and `apis/record_auth_refresh.go`; persistent auth-related models include `core/external_auth_model.go`, `core/mfa_model.go`, and `core/otp_model.go`. JWT/cryptographic primitives are isolated in `tools/security/jwt.go` and `tools/security/crypto.go`; OAuth providers are adapters under `tools/auth/`.

#### Files, Backups, Mail, and Operations
File fields connect record data to a pluggable filesystem boundary (`core/field_file.go`, `tools/filesystem/filesystem.go`). Storage supports local blobs and an S3-compatible implementation (`tools/filesystem/internal/s3blob/s3blob.go`), making object storage the principal external infrastructure option. Backup creation/restoration is core functionality in `core/backup_create.go` and `core/backup_restore.go`, exposed via `apis/backup.go`. Outbound mail is composed from record mail logic and templates (`mails/record.go`, `mails/templates/layout.go`) and sent through SMTP or sendmail adapters (`tools/mailer/smtp.go`, `tools/mailer/sendmail.go`).

#### Admin UI and Schema Operations
The prebuilt admin dashboard is embedded by Go through `ui/embed.go`, with browser assets under `ui/dist/`; source UI routing begins at `ui/src/main.js`. It administers collections, records, logs, backups, storage, mail, cron, SQL, and settings. Schema/data evolution is versioned through `core/migrations_runner.go` and repository migrations in `migrations/`; the migration CLI/plugin layer is `plugins/migratecmd/migratecmd.go`.

Main entry points: [`core/app.go`](https://github.com/pocketbase/pocketbase/blob/master/core/app.go) (Application runtime), [`core/collection_model.go`](https://github.com/pocketbase/pocketbase/blob/master/core/collection_model.go) (Collections, fields & records), [`core/db.go`](https://github.com/pocketbase/pocketbase/blob/master/core/db.go) (Database lifecycle), [`tools/router/router.go`](https://github.com/pocketbase/pocketbase/blob/master/tools/router/router.go) (Router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime &amp; Extensions"]
  node_library["PocketBase library<br/>Go entry point<br/>[pocketbase.go]"]
  node_cli["CLI commands<br/>Cobra commands<br/>[serve.go]"]
  node_app["Application runtime<br/>core runtime<br/>[app.go]"]
  node_events["Event hooks<br/>extension API<br/>[events.go]"]
  node_jsvm{{"JavaScript VM<br/>plugin runtime<br/>[jsvm.go]"}}
end

subgraph group_api["HTTP &amp; Realtime"]
  node_router["Router<br/>[router.go]"]
  node_serve["API serving layer<br/>HTTP registration<br/>[serve.go]"]
  node_records_api["Record API<br/>CRUD endpoints<br/>[record_crud.go]"]
  node_auth_api["Auth API<br/>authentication endpoints"]
  node_realtime["Realtime API<br/>subscription endpoint<br/>[realtime.go]"]
  node_broker["Subscription broker<br/>in-process pub/sub<br/>[broker.go]"]
end

subgraph group_data["Data &amp; Storage"]
  node_models["Collections, fields &amp; records<br/>dynamic data model"]
  node_schema_sync["Record table sync<br/>schema synchronization"]
  node_queries["Record queries<br/>query and expansion<br/>[record_query.go]"]
  node_database[("Database lifecycle<br/>connection and transactions<br/>[db.go]")]
  node_sqlite[("SQLite<br/>embedded database")]
  node_filesystem["Filesystem boundary<br/>pluggable storage<br/>[filesystem.go]"]
  node_object_storage["S3-compatible storage<br/>external object storage<br/>[s3blob.go]"]
end

subgraph group_operations["Operations"]
  node_backup["Backup service<br/>backup and restore<br/>[backup_create.go]"]
  node_mail["Record mail<br/>mail composition<br/>[record.go]"]
end

subgraph group_admin["Admin &amp; Migration"]
  node_admin_ui["Embedded admin UI<br/>browser dashboard<br/>[embed.go]"]
  node_migrations["Migration runner<br/>schema evolution"]
end

node_library -->|"constructs"| node_app
node_cli -->|"serves"| node_app
node_app -->|"emits hooks"| node_events
node_app -->|"hosts plugins"| node_jsvm
node_jsvm -.->|"registers handlers"| node_events
node_app -->|"starts"| node_serve
node_serve -->|"registers routes"| node_router
node_router -->|"dispatches"| node_records_api
node_router -->|"dispatches"| node_auth_api
node_router -->|"upgrades connections"| node_realtime
node_records_api -->|"queries records"| node_queries
node_records_api -->|"mutates records"| node_models
node_auth_api -->|"loads identities"| node_models
node_realtime -->|"subscribes"| node_broker
node_models -->|"defines tables"| node_schema_sync
node_schema_sync -->|"applies schema"| node_database
node_queries -->|"executes"| node_database
node_database -->|"persists to"| node_sqlite
node_models -->|"file fields use"| node_filesystem
node_filesystem -.->|"optional backend"| node_object_storage
node_app -->|"provides"| node_backup
node_backup -->|"backs up and restores"| node_database
node_app -->|"sends notifications"| node_mail
node_serve -->|"serves dashboard"| node_admin_ui
node_migrations -->|"evolves schema"| node_database
node_migrations -->|"updates collections"| node_models

click node_library "https://github.com/pocketbase/pocketbase/blob/master/pocketbase.go"
click node_cli "https://github.com/pocketbase/pocketbase/blob/master/cmd/serve.go"
click node_app "https://github.com/pocketbase/pocketbase/blob/master/core/app.go"
click node_events "https://github.com/pocketbase/pocketbase/blob/master/core/events.go"
click node_jsvm "https://github.com/pocketbase/pocketbase/blob/master/plugins/jsvm/jsvm.go"
click node_router "https://github.com/pocketbase/pocketbase/blob/master/tools/router/router.go"
click node_serve "https://github.com/pocketbase/pocketbase/blob/master/apis/serve.go"
click node_records_api "https://github.com/pocketbase/pocketbase/blob/master/apis/record_crud.go"
click node_auth_api "https://github.com/pocketbase/pocketbase/blob/master/apis/record_auth_with_password.go"
click node_realtime "https://github.com/pocketbase/pocketbase/blob/master/apis/realtime.go"
click node_broker "https://github.com/pocketbase/pocketbase/blob/master/tools/subscriptions/broker.go"
click node_models "https://github.com/pocketbase/pocketbase/blob/master/core/collection_model.go"
click node_schema_sync "https://github.com/pocketbase/pocketbase/blob/master/core/collection_record_table_sync.go"
click node_queries "https://github.com/pocketbase/pocketbase/blob/master/core/record_query.go"
click node_database "https://github.com/pocketbase/pocketbase/blob/master/core/db.go"
click node_filesystem "https://github.com/pocketbase/pocketbase/blob/master/tools/filesystem/filesystem.go"
click node_object_storage "https://github.com/pocketbase/pocketbase/blob/master/tools/filesystem/internal/s3blob/s3blob.go"
click node_backup "https://github.com/pocketbase/pocketbase/blob/master/core/backup_create.go"
click node_mail "https://github.com/pocketbase/pocketbase/blob/master/mails/record.go"
click node_admin_ui "https://github.com/pocketbase/pocketbase/blob/master/ui/embed.go"
click node_migrations "https://github.com/pocketbase/pocketbase/blob/master/core/migrations_runner.go"

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_library,node_cli,node_app,node_events,node_jsvm toneBlue
class node_router,node_serve,node_records_api,node_auth_api,node_realtime,node_broker toneAmber
class node_models,node_schema_sync,node_queries,node_database,node_sqlite,node_filesystem,node_object_storage toneMint
class node_backup,node_mail toneRose
class node_admin_ui,node_migrations toneIndigo
```

## Components

### Runtime & Extensions

- [PocketBase library](https://github.com/pocketbase/pocketbase/blob/master/pocketbase.go): Go entry point · Embeddable application construction and startup. · `pocketbase.go`
- [CLI commands](https://github.com/pocketbase/pocketbase/blob/master/cmd/serve.go): Cobra commands · `cmd/serve.go`
- [Application runtime](https://github.com/pocketbase/pocketbase/blob/master/core/app.go): core runtime · Owns services and lifecycle. · `core/app.go`
- [Event hooks](https://github.com/pocketbase/pocketbase/blob/master/core/events.go): extension API · `core/events.go`
- [JavaScript VM](https://github.com/pocketbase/pocketbase/blob/master/plugins/jsvm/jsvm.go): plugin runtime · Hosts JavaScript extensions with application bindings. · `plugins/jsvm/jsvm.go`

### HTTP & Realtime

- [Router](https://github.com/pocketbase/pocketbase/blob/master/tools/router/router.go): HTTP router · `tools/router/router.go`
- [API serving layer](https://github.com/pocketbase/pocketbase/blob/master/apis/serve.go): HTTP registration · Registers endpoints and middleware. · `apis/serve.go`
- [Record API](https://github.com/pocketbase/pocketbase/blob/master/apis/record_crud.go): CRUD endpoints · `apis/record_crud.go`
- [Auth API](https://github.com/pocketbase/pocketbase/blob/master/apis/record_auth_with_password.go): authentication endpoints · Password, OAuth2, refresh, and related identity flows. · `apis/record_auth_with_password.go`
- [Realtime API](https://github.com/pocketbase/pocketbase/blob/master/apis/realtime.go): subscription endpoint · `apis/realtime.go`
- [Subscription broker](https://github.com/pocketbase/pocketbase/blob/master/tools/subscriptions/broker.go): in-process pub/sub · `tools/subscriptions/broker.go`

### Data & Storage

- [Collections, fields & records](https://github.com/pocketbase/pocketbase/blob/master/core/collection_model.go): dynamic data model · Collection definitions govern records and fields. · `core/collection_model.go`
- [Record table sync](https://github.com/pocketbase/pocketbase/blob/master/core/collection_record_table_sync.go): schema synchronization · `core/collection_record_table_sync.go`
- [Record queries](https://github.com/pocketbase/pocketbase/blob/master/core/record_query.go): query and expansion · `core/record_query.go`
- [Database lifecycle](https://github.com/pocketbase/pocketbase/blob/master/core/db.go): connection and transactions · `core/db.go`
- **SQLite**: embedded database
- [Filesystem boundary](https://github.com/pocketbase/pocketbase/blob/master/tools/filesystem/filesystem.go): pluggable storage · Supports local and S3-compatible blobs. · `tools/filesystem/filesystem.go`
- [S3-compatible storage](https://github.com/pocketbase/pocketbase/blob/master/tools/filesystem/internal/s3blob/s3blob.go): external object storage · `tools/filesystem/internal/s3blob/s3blob.go`

### Operations

- [Backup service](https://github.com/pocketbase/pocketbase/blob/master/core/backup_create.go): backup and restore · `core/backup_create.go`
- [Record mail](https://github.com/pocketbase/pocketbase/blob/master/mails/record.go): mail composition · `mails/record.go`

### Admin & Migration

- [Embedded admin UI](https://github.com/pocketbase/pocketbase/blob/master/ui/embed.go): browser dashboard · Prebuilt dashboard embedded into the server. · `ui/embed.go`
- [Migration runner](https://github.com/pocketbase/pocketbase/blob/master/core/migrations_runner.go): schema evolution · Runs versioned repository migrations. · `core/migrations_runner.go`

## Connections

- PocketBase library → Application runtime: constructs
- CLI commands → Application runtime: serves
- Application runtime → Event hooks: emits hooks
- Application runtime → JavaScript VM: hosts plugins
- JavaScript VM → Event hooks: registers handlers
- Application runtime → API serving layer: starts
- API serving layer → Router: registers routes
- Router → Record API: dispatches
- Router → Auth API: dispatches
- Router → Realtime API: upgrades connections
- Record API → Record queries: queries records
- Record API → Collections, fields & records: mutates records
- Auth API → Collections, fields & records: loads identities
- Realtime API → Subscription broker: subscribes
- Collections, fields & records → Record table sync: defines tables
- Record table sync → Database lifecycle: applies schema
- Record queries → Database lifecycle: executes
- Database lifecycle → SQLite: persists to
- Collections, fields & records → Filesystem boundary: file fields use
- Filesystem boundary → S3-compatible storage: optional backend
- Application runtime → Backup service: provides
- Backup service → Database lifecycle: backs up and restores
- Application runtime → Record mail: sends notifications
- API serving layer → Embedded admin UI: serves dashboard
- Migration runner → Database lifecycle: evolves schema
- Migration runner → Collections, fields & records: updates collections
