How pocketbase/pocketbase works
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: app.go Application runtime · collection_model.go Collections, fields & records · db.go Database lifecycle · router.go Router
Components 22
Runtime & Extensions
- PocketBase library · Embeddable application construction and startup.
pocketbase.go - CLI commands
cmd/serve.go - Application runtime · Owns services and lifecycle.
core/app.go - Event hooks
core/events.go - JavaScript VM · Hosts JavaScript extensions with application bindings.
plugins/jsvm/jsvm.go
HTTP & Realtime
- Router
tools/router/router.go - API serving layer · Registers endpoints and middleware.
apis/serve.go - Record API
apis/record_crud.go - Auth API · Password, OAuth2, refresh, and related identity flows.
apis/record_auth_with_password.go - Realtime API
apis/realtime.go - Subscription broker
tools/subscriptions/broker.go
Data & Storage
- Collections, fields & records · Collection definitions govern records and fields.
core/collection_model.go - Record table sync
core/collection_record_table_sync.go - Record queries
core/record_query.go - Database lifecycle
core/db.go - SQLite
- Filesystem boundary · Supports local and S3-compatible blobs.
tools/filesystem/filesystem.go - S3-compatible storage
tools/filesystem/internal/s3blob/s3blob.go
Operations
- Backup service
core/backup_create.go - Record mail
mails/record.go
Admin & Migration
- Embedded admin UI · Prebuilt dashboard embedded into the server.
ui/embed.go - Migration runner · Runs versioned repository migrations.
core/migrations_runner.go
Connections 26
- 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