This page provides a high-level introduction to Drivebase, explaining its purpose, architecture, and key technical characteristics. For detailed information about specific subsystems, refer to the linked pages throughout this document.
Drivebase is a cloud-agnostic file management platform that unifies files and folders across multiple storage providers under a single interface. This document covers the system's overall architecture, monorepo structure, provider abstraction layer, and deployment models. For specific provider implementations, see Supported Providers. For database schema details, see Database Schema.
Drivebase is a self-hosted application that provides a unified file management experience across heterogeneous storage backends. Users can connect multiple providers (S3, Google Drive, Dropbox, Local, FTP, WebDAV, Telegram, Nextcloud, Darkibox) and manage all their files through a single interface.
Core Value Proposition:
| Feature | Description |
|---|---|
| Unified Workspace | Browse and manage files from multiple providers in one interface |
| Smart Search | Full-text search with OCR and document extraction across all providers |
| Smart Uploads | Automated file routing based on configurable rules |
| End-to-End Encryption | Client-side encrypted vault for sensitive files |
| Multi-Tenancy | Workspace-based organization with role-based access control |
| Self-Hosted | Docker-based deployment with full data ownership |
Sources: README.md27-40 apps/www/content/docs/storage-providers/overview.mdx6-7
Sources: package.json1-44 apps/api/package.json17-51
Drivebase uses a Bun workspace-based monorepo with Turbo for build orchestration. The codebase is organized into applications and shared packages.
Workspace Configuration:
The monorepo is defined in package.json5-8 with workspaces for apps/* and packages/*. The package manager is specified as bun@1.3.5 in package.json43
Key Scripts:
| Script | Purpose | Implementation |
|---|---|---|
generate | Run code generation (GraphQL, routes) | package.json10 |
dev | Start API and web in parallel | package.json11 |
build | Build web frontend | package.json12 |
db:migrate | Run database migrations | package.json18 |
check-types | TypeScript type checking across packages | package.json16 |
Sources: package.json1-44
Drivebase implements a three-tier architecture with a React frontend, GraphQL/REST API backend, and a pluggable provider layer.
Layer Responsibilities:
Client Tier (apps/web): React SPA with TanStack Router for routing, URQL for GraphQL queries, Zustand for state management. See Frontend Application Architecture for details.
Application Tier (apps/api): Hono HTTP server hosting both GraphQL (via graphql-yoga) and REST endpoints. Services interact with the provider registry and database.
Provider Tier (packages/*-provider): Pluggable provider implementations that all extend BaseProvider from @drivebase/core. Each provider package exports a registration object for the registry.
Data Tier: PostgreSQL with pgvector extension for semantic search, Redis for caching and BullMQ job queues.
Sources: apps/api/package.json1-65 apps/api/config/providers.ts35-45 docker/compose.prod.yaml45-78
The provider system is the architectural centerpiece of Drivebase. It implements a registry pattern where each storage backend is a separate package implementing a common interface.
Registry Structure:
The providerRegistry object in apps/api/config/providers.ts35-45 maps ProviderType enum values to ProviderRegistration objects. Each registration contains:
| Field | Type | Purpose |
|---|---|---|
factory | () => BaseProvider | Factory function to instantiate the provider |
configSchema | ZodSchema | Validation schema for provider config |
configFields | ProviderConfigField[] | UI field definitions for connection form |
description | string | Human-readable provider description |
authType | 'oauth' | 'api_key' | 'email_pass' | 'no_auth' | Authentication method |
supportsPresignedUrls | boolean | Whether provider supports direct upload URLs |
Provider Types:
The providerTypeEnum in packages/db/schema/providers.ts17-27 defines the supported provider types:
google_drive: Google Drive OAuth integrations3: S3-compatible storage (AWS, MinIO, R2, etc.)local: Local filesystem pathsdropbox: Dropbox OAuth integrationftp: FTP/FTPS serverswebdav: WebDAV servers (Nextcloud, ownCloud)telegram: Telegram Saved Messagesnextcloud: Nextcloud Login Flow v2darkibox: Darkibox API key authenticationSources: apps/api/config/providers.ts35-45 packages/core/enums.ts32-51 packages/db/schema/providers.ts17-27 packages/dropbox/schema.ts10-19 packages/darkibox/schema.ts4-8
Encrypted Configuration:
Provider credentials are stored encrypted in the encryptedConfig column of the storageProviders table (packages/db/schema/providers.ts49). The encryption uses AES-256-GCM with the ENCRYPTION_KEY environment variable.
Sensitive Fields by Provider:
Each provider package exports a SensitiveFields constant defining which config fields require encryption:
appSecret, refreshToken, accessToken (packages/dropbox/schema.ts26-30)apiKey (packages/darkibox/schema.ts11)The registry aggregates these in apps/api/config/providers.ts50-60
OAuth Credential Reuse:
The oauthProviderCredentials table (packages/db/schema/providers.ts72-99) stores reusable OAuth app credentials (client ID/secret) separately from provider instances, allowing users to connect multiple accounts with the same OAuth app. See OAuth Authentication for details.
Sources: packages/db/schema/providers.ts42-106 apps/api/config/providers.ts50-60 packages/dropbox/schema.ts26-30 packages/darkibox/schema.ts11
Drivebase requires two external services to operate:
Purpose: Primary database for all application data and semantic search.
Docker Image: pgvector/pgvector:pg17 (docker/compose.prod.yaml46)
Required Extensions:
pgvector: Vector similarity search for file content embeddingsConnection: Configured via DATABASE_URL environment variable (example: postgres://postgres:postgres@db:5432/drivebase)
Tables: See Database Schema for complete schema documentation.
Purpose: Caching and BullMQ job queue backend.
Docker Image: redis:7-alpine (docker/compose.prod.yaml66)
Connection: Configured via REDIS_URL environment variable (example: redis://redis:6379)
Usage:
Sources: docker/compose.prod.yaml45-78 apps/api/package.json35-40
Drivebase supports three deployment strategies with different trade-offs:
Configuration: docker/compose.prod.yaml1-88
Services:
app: Main application container (ghcr.io/drivebase/drivebase:v3.4.1)updater: Auto-update sidecar with Docker socket accessdb: PostgreSQL with pgvectorredis: Redis cache/queueUnique Features:
Installation:
See Docker Compose Deployment for detailed instructions.
Configuration: render.yaml1-49
Services:
ghcr.io/drivebase/drivebase:v3.4.1)Features:
Limitations:
Configuration: railway.json1-6
Deployment: Uses the same docker/compose.prod.yaml via Docker Compose
Features:
Sources: docker/compose.prod.yaml1-88 render.yaml1-49 railway.json1-6 README.md62-67
Drivebase uses semantic versioning with automated releases via GitHub Actions.
Current Version: 3.4.1 (package.json3 CHANGELOG.md3)
Release Process:
v* patternghcr.io/drivebase/drivebase:v{version}Version Bumping: Managed by release-it (.release-it.json1-54) which updates:
Changelog Format: Conventional commits with categorized sections (Features, Fixes, Styles, Others) as defined in .release-it.json14-36
See Release Process for complete pipeline documentation.
Sources: package.json3 CHANGELOG.md1-15 .release-it.json1-54 docker/compose.prod.yaml3-32 render.yaml5
All files and folders from different providers are unified in a single nodes table with both virtualPath (user-facing) and remoteId (provider-specific) fields. This enables:
See Virtual File System for implementation details.
Workspaces provide organizational isolation with workspace-scoped resources:
See Workspaces and Permissions for details.
Async operations are queued via BullMQ with Redis as the backing store:
See Background Jobs System for implementation.
The Vault feature provides end-to-end encryption where files are encrypted in the browser before upload. The API never sees plaintext content. See Vault - End-to-End Encryption for cryptographic details.
Frontend supports three languages with Lingui i18n framework:
See Internationalization for translation workflow.
Sources: README.md27-40 apps/api/package.json35-40
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.