Vaultwarden Architecture Diagram: How the Codebase Works

Project Overview

Unofficial Bitwarden compatible server written in Rust, formerly known as bitwarden_rs

Category

application

Difficulty

intermediate

Tech Stack

Rust

Author

dani-garcia

Tags

self-hosted, rust, security

How vaultwarden Works

Vaultwarden is a secure, self-hosted password and credential management solution, functioning as a lightweight alternative server implementation of the Bitwarden Client API. Its core business domain revolves around providing robust data security and privacy for users' digital credentials, offering features like encrypted vault item storage, secure temporary sharing, organization management with role-based access control, and emergency access provisioning. It serves individuals and organizations seeking to self-host their password manager infrastructure, ensuring full control over their sensitive data without the resource overhead of the official Bitwarden server.

Data Flow

The data flow in Vaultwarden is primarily driven by client-side cryptography and a layered API backend. Users interact with official Bitwarden clients (web, desktop, mobile), which perform initial encryption of sensitive vault data (Ciphers) using a key derived from the user's master password (zero-knowledge principle). These encrypted payloads are then sent over HTTPS to the Vaultwarden Rocket API (`src/api/*`). The API acts as a secure intermediary, authenticating requests via JSON Web Tokens (`src/auth.rs`) and validating business logic. Domain-specific data, such as encrypted `Cipher` items (`src/db/models/cipher.rs`), `User` profiles (`src/db/models/user.rs`), `Send` items (`src/db/models/send.rs`), `Organization` configurations (`src/db/models/organization.rs`), `EmergencyAccess` grants (`src/db/models/emergency_access.rs`), and `TwoFactor` settings (`src/db/models/two_factor.rs`), are then persisted to a relational database (managed by Diesel via `src/db/schema.rs`). File attachments (e.g., for 'Sends') are stored through a storage abstraction (`src/storage.rs`) that can target local filesystems or S3-compatible services. When clients request data (e.g., during vault synchronization via `GET /api/sync`), the API retrieves the encrypted records from the database, serializes them, and sends them back. The client is then responsible for decrypting the data locally for display to the user. All critical cryptographic operations, including Key Derivation Functions (KDFs), hashing, and secure random number generation, are managed by `src/crypto.rs` to ensure consistent and secure primitives throughout the system.

Get a free architecture diagram of your own codebase

Want this for your own code? Vaultwarden took one URL and about a minute. Get a free architecture diagram for your own repo — paste a GitHub URL or drop a ZIP, and the diagrams, module map and execution flows come back in about a minute. First project is free.

Key Modules & Components

• User Account & Vault Management: Manages the complete lifecycle of user accounts, including registration, profile management, and the secure storage, retrieval, and modification of their encrypted vault items (ciphers) and attachments. This module ensures that core user data and their digital credentials are securely processed and accessible.
  Key files: src/api/identity.rs, src/db/models/user.rs, src/api/core/accounts.rs
• Secure Sharing (Sends) Service: Provides functionality for users to securely and temporarily share sensitive textual information or files. This includes managing creation, access control, password protection, encryption, tracking access counts, and expiration of 'Send' items.
  Key files: src/db/models/send.rs, src/api/core/sends.rs
• Organization & Collaborative Vaults: Enables the creation and management of organizations, facilitating shared vault items, role-based access control (RBAC), user invitations, and collection management for collaborative security within a team or enterprise setting.
  Key files: src/db/models/organization.rs, src/api/core/organizations.rs
• Emergency Access Management: Allows users to configure and manage trusted contacts who can gain conditional access to their vault in emergency situations. This ensures data accessibility and recovery according to predefined policies and waiting periods.
  Key files: src/db/models/emergency_access.rs, src/api/core/emergency_access.rs
• Single Sign-On (SSO) Integration: Integrates the application with external OpenID Connect (OIDC) identity providers, enabling users to authenticate using existing corporate or third-party credentials. This streamlines the login process and enhances enterprise security.
  Key files: src/sso.rs, src/sso_client.rs
• Authentication & Cryptographic Services: Provides core security primitives, including cryptographic hashing, encryption, secure random generation, and constant-time comparisons. It also manages JSON Web Token (JWT) based authentication and authorization, along with two-factor authentication (2FA) mechanisms to secure user access.
  Key files: src/crypto.rs, src/auth.rs, src/db/models/two_factor.rs
• Application Core & Web Infrastructure: The foundational layer responsible for application startup, command-line utilities, configuration management, general error handling, abstracting persistent storage solutions (local filesystem, S3), sending email notifications, and serving the static web vault interface along with common API utilities.
  Key files: src/main.rs, src/config.rs, src/error.rs
• Database Schema & Connection Management: Defines the application's relational database schema using Diesel ORM and provides the interface for database connection pooling, migration management, and overall abstraction of persistence details from the business logic layer.
  Key files: src/db/schema.rs, src/db/mod.rs, src/db/models/mod.rs

Related Architecture Deep Dives

• Vlc Architecture Diagram — Rust, C
• Excalidraw Architecture Diagram — typescript, vite, react
• T3code Architecture Diagram — react, astro, SQLite
• Pickle-glass Architecture Diagram — electron, NextJS, Express
• Codex Architecture Diagram — Rust