# dani-garcia/vaultwarden architecture

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

- Interactive diagram: https://gitdiagram.com/dani-garcia/vaultwarden
- Repository: https://github.com/dani-garcia/vaultwarden

## Overview

Vaultwarden is a self-hosted Bitwarden-compatible API server. Official clients send authenticated requests to Rocket routes, which validate identity and security requirements, execute vault, sharing, organization, Send, emergency-access, or administration operations, persist state, and return JSON results. Optional flows integrate with SMTP, push services, Duo, OIDC, WebAuthn, website-icon providers, and S3-compatible storage. The graph emphasizes documented capabilities and sampled module boundaries; several route implementations were not inspected, so unsupported internal call chains are omitted.

Main entry points: [`src/db/mod.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/src/db/mod.rs) (Application Database), [`src/api/core/mod.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/mod.rs) (Core API Routes), [`src/api/core/two_factor/mod.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/two_factor/mod.rs) (Two-Factor Auth), [`src/http_client.rs`](https://github.com/dani-garcia/vaultwarden/blob/main/src/http_client.rs) (HTTP Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Surface"]
  node_core_routes["Core API Routes<br/>[mod.rs]"]
  node_admin_routes["Admin Routes<br/>[admin.rs]"]
  node_web_routes["Web Routes<br/>[web.rs]"]
  node_notifications["Notifications<br/>[notifications.rs]"]
  node_push["Push Service<br/>[push.rs]"]
end

subgraph group_domain["Vault Domains"]
  node_vault_items["Personal Vault<br/>[ciphers.rs]"]
  node_folders["Folders<br/>[folders.rs]"]
  node_sends["Secure Sends<br/>[sends.rs]"]
  node_organizations["Organizations<br/>[organizations.rs]"]
  node_collections["Collections Sharing<br/>[collection.rs]"]
  node_emergency_access["Emergency Access"]
end

subgraph group_security["Identity Security"]
  node_auth_identity["Authentication<br/>[auth.rs]"]
  node_two_factor["Two-Factor Auth<br/>[mod.rs]"]
  node_webauthn["WebAuthn<br/>[webauthn.rs]"]
  node_sso["SSO Login<br/>[sso.rs]"]
end

subgraph group_persistence["Persistence"]
  node_database[("Application Database<br/>[mod.rs]")]
  node_file_storage[("File Storage<br/>[storage.rs]")]
  node_scheduler["Maintenance Jobs<br/>[main.rs]"]
end

subgraph group_integrations["External Integrations"]
  node_http_client["HTTP Client<br/>[http_client.rs]"]
  node_mail["Email Delivery<br/>[mail.rs]"]
end

node_bitwarden_clients(("Bitwarden Clients"))
node_admin_operator(("Admin Operator"))
node_oidc_provider["OIDC Provider"]
node_duo_service["Duo Service"]
node_s3_storage[("S3 Storage")]
node_icon_provider["Icon Provider"]

node_bitwarden_clients -->|"sends requests"| node_core_routes
node_bitwarden_clients -->|"loads web UI"| node_web_routes
node_admin_operator -->|"manages server"| node_admin_routes
node_core_routes -->|"authenticates"| node_auth_identity
node_core_routes -->|"dispatches vault"| node_vault_items
node_core_routes -->|"dispatches folders"| node_folders
node_core_routes -->|"dispatches sends"| node_sends
node_core_routes -->|"dispatches orgs"| node_organizations
node_core_routes -->|"dispatches access"| node_emergency_access
node_organizations -->|"manages sharing"| node_collections
node_auth_identity -->|"reads users"| node_database
node_vault_items -->|"reads and writes"| node_database
node_folders -->|"reads and writes"| node_database
node_sends -->|"reads and writes"| node_database
node_organizations -->|"reads and writes"| node_database
node_collections -->|"reads and writes"| node_database
node_emergency_access -->|"reads and writes"| node_database
node_two_factor -->|"stores factors"| node_database
node_webauthn -->|"stores challenges"| node_database
node_core_routes -->|"dispatches 2FA"| node_two_factor
node_two_factor -.->|"sends codes"| node_mail
node_two_factor -.->|"verifies Duo"| node_duo_service
node_webauthn -->|"uses transport"| node_http_client
node_sso -->|"executes OIDC"| node_http_client
node_sso -->|"stores login state"| node_database
node_sso -.->|"discovers identity"| node_oidc_provider
node_admin_routes -->|"reads and writes"| node_database
node_core_routes -->|"stores attachments"| node_file_storage
node_file_storage -.->|"accesses objects"| node_s3_storage
node_core_routes -->|"fetches icons"| node_http_client
node_http_client -.->|"requests icons"| node_icon_provider
node_notifications -->|"delivers notices"| node_mail
node_notifications -->|"dispatches pushes"| node_push
node_scheduler -->|"purges records"| node_database

click node_core_routes "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/mod.rs"
click node_admin_routes "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/admin.rs"
click node_web_routes "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/web.rs"
click node_notifications "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/notifications.rs"
click node_push "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/push.rs"
click node_vault_items "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/ciphers.rs"
click node_folders "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/folders.rs"
click node_sends "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/sends.rs"
click node_organizations "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/organizations.rs"
click node_collections "https://github.com/dani-garcia/vaultwarden/blob/main/src/db/models/collection.rs"
click node_emergency_access "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/emergency_access.rs"
click node_auth_identity "https://github.com/dani-garcia/vaultwarden/blob/main/src/auth.rs"
click node_two_factor "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/two_factor/mod.rs"
click node_webauthn "https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/two_factor/webauthn.rs"
click node_sso "https://github.com/dani-garcia/vaultwarden/blob/main/src/sso.rs"
click node_database "https://github.com/dani-garcia/vaultwarden/blob/main/src/db/mod.rs"
click node_file_storage "https://github.com/dani-garcia/vaultwarden/blob/main/src/storage.rs"
click node_scheduler "https://github.com/dani-garcia/vaultwarden/blob/main/src/main.rs"
click node_http_client "https://github.com/dani-garcia/vaultwarden/blob/main/src/http_client.rs"
click node_mail "https://github.com/dani-garcia/vaultwarden/blob/main/src/mail.rs"

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_core_routes,node_admin_routes,node_web_routes,node_notifications,node_push,node_bitwarden_clients toneBlue
class node_vault_items,node_folders,node_sends,node_organizations,node_collections,node_emergency_access,node_s3_storage toneAmber
class node_auth_identity,node_two_factor,node_webauthn,node_sso toneMint
class node_database,node_file_storage,node_scheduler toneRose
class node_http_client,node_mail,node_admin_operator,node_oidc_provider,node_duo_service,node_icon_provider toneIndigo
```

## Components

### API Surface

- [Core API Routes](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/mod.rs): `src/api/core/mod.rs`
- [Admin Routes](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/admin.rs): `src/api/admin.rs`
- [Web Routes](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/web.rs): `src/api/web.rs`
- [Notifications](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/notifications.rs): `src/api/notifications.rs`
- [Push Service](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/push.rs): `src/api/push.rs`

### Vault Domains

- [Personal Vault](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/ciphers.rs): `src/api/core/ciphers.rs`
- [Folders](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/folders.rs): `src/api/core/folders.rs`
- [Secure Sends](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/sends.rs): `src/api/core/sends.rs`
- [Organizations](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/organizations.rs): `src/api/core/organizations.rs`
- [Collections Sharing](https://github.com/dani-garcia/vaultwarden/blob/main/src/db/models/collection.rs): `src/db/models/collection.rs`
- [Emergency Access](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/emergency_access.rs): `src/api/core/emergency_access.rs`

### Identity Security

- [Authentication](https://github.com/dani-garcia/vaultwarden/blob/main/src/auth.rs): `src/auth.rs`
- [Two-Factor Auth](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/two_factor/mod.rs): `src/api/core/two_factor/mod.rs`
- [WebAuthn](https://github.com/dani-garcia/vaultwarden/blob/main/src/api/core/two_factor/webauthn.rs): `src/api/core/two_factor/webauthn.rs`
- [SSO Login](https://github.com/dani-garcia/vaultwarden/blob/main/src/sso.rs): `src/sso.rs`

### Persistence

- [Application Database](https://github.com/dani-garcia/vaultwarden/blob/main/src/db/mod.rs): `src/db/mod.rs`
- [File Storage](https://github.com/dani-garcia/vaultwarden/blob/main/src/storage.rs): `src/storage.rs`
- [Maintenance Jobs](https://github.com/dani-garcia/vaultwarden/blob/main/src/main.rs): `src/main.rs`

### External Integrations

- [HTTP Client](https://github.com/dani-garcia/vaultwarden/blob/main/src/http_client.rs): `src/http_client.rs`
- [Email Delivery](https://github.com/dani-garcia/vaultwarden/blob/main/src/mail.rs): `src/mail.rs`

### Other components

- **Bitwarden Clients**
- **Admin Operator**
- **OIDC Provider**
- **Duo Service**
- **S3 Storage**
- **Icon Provider**

## Connections

- Bitwarden Clients → Core API Routes: sends requests
- Bitwarden Clients → Web Routes: loads web UI
- Admin Operator → Admin Routes: manages server
- Core API Routes → Authentication: authenticates
- Core API Routes → Personal Vault: dispatches vault
- Core API Routes → Folders: dispatches folders
- Core API Routes → Secure Sends: dispatches sends
- Core API Routes → Organizations: dispatches orgs
- Core API Routes → Emergency Access: dispatches access
- Organizations → Collections Sharing: manages sharing
- Authentication → Application Database: reads users
- Personal Vault → Application Database: reads and writes
- Folders → Application Database: reads and writes
- Secure Sends → Application Database: reads and writes
- Organizations → Application Database: reads and writes
- Collections Sharing → Application Database: reads and writes
- Emergency Access → Application Database: reads and writes
- Two-Factor Auth → Application Database: stores factors
- WebAuthn → Application Database: stores challenges
- Core API Routes → Two-Factor Auth: dispatches 2FA
- Two-Factor Auth → Email Delivery: sends codes
- Two-Factor Auth → Duo Service: verifies Duo
- WebAuthn → HTTP Client: uses transport
- SSO Login → HTTP Client: executes OIDC
- SSO Login → Application Database: stores login state
- SSO Login → OIDC Provider: discovers identity
- Admin Routes → Application Database: reads and writes
- Core API Routes → File Storage: stores attachments
- File Storage → S3 Storage: accesses objects
- Core API Routes → HTTP Client: fetches icons
- HTTP Client → Icon Provider: requests icons
- Notifications → Email Delivery: delivers notices
- Notifications → Push Service: dispatches pushes
- Maintenance Jobs → Application Database: purges records
