# acevflow/lockwell architecture

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

- Interactive diagram: https://gitdiagram.com/acevflow/lockwell
- Repository: https://github.com/acevflow/lockwell

## Overview

lockwell is a local-only Tauri desktop vault for passwords and private files. The main workflow is to create or restore a vault, unlock it with the master password, manage entries and files, and lock it when requested or automatically. Encrypted backups support recovery or migration; clipboard protection and password changes are additional security capabilities. The graph combines documented product behavior with visible UI/API wiring and command registration; unsampled Rust command-to-vault internals are not asserted.

Main entry points: [`src-tauri/src/commands`](https://github.com/acevflow/lockwell/tree/main/src-tauri/src/commands) (Tauri commands), [`src-tauri/src/vault/session.rs`](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/session.rs) (Vault session), [`src/api/client.ts`](https://github.com/acevflow/lockwell/blob/main/src/api/client.ts) (Tauri API client), [`src/App.tsx`](https://github.com/acevflow/lockwell/blob/main/src/App.tsx) (App flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Desktop interface"]
  node_app["App flow<br/>[App.tsx]"]
  node_setup["Vault setup<br/>[SetupScreen.tsx]"]
  node_vaultscreen["Vault screen<br/>[VaultScreen.tsx]"]
  node_filesui["File manager UI<br/>[FilesTab.tsx]"]
  node_backupui["Backup forms"]
end

subgraph group_boundary["Command boundary"]
  node_api["Tauri API client<br/>[client.ts]"]
  node_vaultapi["Vault API<br/>[vault.ts]"]
  node_securityapi["Security API<br/>[security.ts]"]
  node_fileapi["File API<br/>[files.ts]"]
  node_backupapi["Backup API<br/>[backup.ts]"]
  node_commands["Tauri commands"]
end

subgraph group_vault["Vault and storage"]
  node_session["Vault session<br/>[session.rs]"]
  node_entries["Password entries<br/>[entries.rs]"]
  node_files["Encrypted files<br/>[files.rs]"]
  node_backups["Encrypted backups<br/>[backup.rs]"]
  node_header["Vault header<br/>[header.rs]"]
  node_database[("SQLite storage<br/>[db.rs]")]
end

subgraph group_security["Security and cryptography"]
  node_crypto["Cryptographic core"]
  node_security["Lock and clipboard"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"checks status"| node_vaultapi
node_app -->|"shows setup"| node_setup
node_app -->|"shows unlocked vault"| node_vaultscreen
node_setup -->|"creates vault"| node_vaultapi
node_setup -->|"offers restore"| node_backupui
node_vaultscreen -->|"shows files"| node_filesui
node_filesui -->|"manages files"| node_fileapi
node_backupui -->|"restores backup"| node_backupapi
node_vaultapi -->|"invokes commands"| node_api
node_securityapi -->|"invokes commands"| node_api
node_backupapi -->|"invokes commands"| node_api
node_fileapi -->|"invokes commands"| node_api
node_api -->|"dispatches invokes"| node_commands
node_commands -.->|"routes vault operations"| node_session
node_commands -.->|"routes entry operations"| node_entries
node_commands -.->|"routes file operations"| node_files
node_commands -.->|"routes backup operations"| node_backups
node_session -->|"uses vault metadata"| node_header
node_session -->|"uses storage"| node_database
node_session -->|"derives vault key"| node_crypto
node_entries -.->|"stores encrypted records"| node_database
node_entries -.->|"encrypts records"| node_crypto
node_files -.->|"encrypts file chunks"| node_crypto
node_backups -.->|"encrypts backup"| node_crypto
node_securityapi -.->|"requests lock services"| node_security
node_security -.->|"locks vault"| node_session

click node_app "https://github.com/acevflow/lockwell/blob/main/src/App.tsx"
click node_setup "https://github.com/acevflow/lockwell/blob/main/src/screens/SetupScreen.tsx"
click node_vaultscreen "https://github.com/acevflow/lockwell/blob/main/src/screens/VaultScreen.tsx"
click node_filesui "https://github.com/acevflow/lockwell/blob/main/src/screens/FilesTab.tsx"
click node_backupui "https://github.com/acevflow/lockwell/blob/main/src/components/RestoreBackupForm.tsx"
click node_api "https://github.com/acevflow/lockwell/blob/main/src/api/client.ts"
click node_vaultapi "https://github.com/acevflow/lockwell/blob/main/src/api/vault.ts"
click node_securityapi "https://github.com/acevflow/lockwell/blob/main/src/api/security.ts"
click node_fileapi "https://github.com/acevflow/lockwell/blob/main/src/api/files.ts"
click node_backupapi "https://github.com/acevflow/lockwell/blob/main/src/api/backup.ts"
click node_commands "https://github.com/acevflow/lockwell/tree/main/src-tauri/src/commands"
click node_session "https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/session.rs"
click node_entries "https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/entries.rs"
click node_files "https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/files.rs"
click node_backups "https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/backup.rs"
click node_header "https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/header.rs"
click node_database "https://github.com/acevflow/lockwell/blob/main/src-tauri/src/storage/db.rs"
click node_crypto "https://github.com/acevflow/lockwell/tree/main/src-tauri/src/crypto"
click node_security "https://github.com/acevflow/lockwell/tree/main/src-tauri/src/security"

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_app,node_setup,node_vaultscreen,node_filesui,node_backupui,node_user toneBlue
class node_api,node_vaultapi,node_securityapi,node_fileapi,node_backupapi,node_commands toneAmber
class node_session,node_entries,node_files,node_backups,node_header,node_database toneMint
class node_crypto,node_security toneRose
```

## Components

### Desktop interface

- [App flow](https://github.com/acevflow/lockwell/blob/main/src/App.tsx): `src/App.tsx`
- [Vault setup](https://github.com/acevflow/lockwell/blob/main/src/screens/SetupScreen.tsx): `src/screens/SetupScreen.tsx`
- [Vault screen](https://github.com/acevflow/lockwell/blob/main/src/screens/VaultScreen.tsx): `src/screens/VaultScreen.tsx`
- [File manager UI](https://github.com/acevflow/lockwell/blob/main/src/screens/FilesTab.tsx): `src/screens/FilesTab.tsx`
- [Backup forms](https://github.com/acevflow/lockwell/blob/main/src/components/RestoreBackupForm.tsx): `src/components/RestoreBackupForm.tsx`

### Command boundary

- [Tauri API client](https://github.com/acevflow/lockwell/blob/main/src/api/client.ts): `src/api/client.ts`
- [Vault API](https://github.com/acevflow/lockwell/blob/main/src/api/vault.ts): `src/api/vault.ts`
- [Security API](https://github.com/acevflow/lockwell/blob/main/src/api/security.ts): `src/api/security.ts`
- [File API](https://github.com/acevflow/lockwell/blob/main/src/api/files.ts): `src/api/files.ts`
- [Backup API](https://github.com/acevflow/lockwell/blob/main/src/api/backup.ts): `src/api/backup.ts`
- [Tauri commands](https://github.com/acevflow/lockwell/tree/main/src-tauri/src/commands): `src-tauri/src/commands`

### Vault and storage

- [Vault session](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/session.rs): `src-tauri/src/vault/session.rs`
- [Password entries](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/entries.rs): `src-tauri/src/vault/entries.rs`
- [Encrypted files](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/files.rs): `src-tauri/src/vault/files.rs`
- [Encrypted backups](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/backup.rs): `src-tauri/src/vault/backup.rs`
- [Vault header](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/vault/header.rs): `src-tauri/src/vault/header.rs`
- [SQLite storage](https://github.com/acevflow/lockwell/blob/main/src-tauri/src/storage/db.rs): `src-tauri/src/storage/db.rs`

### Security and cryptography

- [Cryptographic core](https://github.com/acevflow/lockwell/tree/main/src-tauri/src/crypto): `src-tauri/src/crypto`
- [Lock and clipboard](https://github.com/acevflow/lockwell/tree/main/src-tauri/src/security): `src-tauri/src/security`

### Other components

- **User**

## Connections

- User → App flow: uses (evidence: `README.md`)
- App flow → Vault API: checks status (evidence: `src/App.tsx`)
- App flow → Vault setup: shows setup (evidence: `src/App.tsx`)
- App flow → Vault screen: shows unlocked vault (evidence: `src/App.tsx`)
- Vault setup → Vault API: creates vault (evidence: `src/screens/SetupScreen.tsx`)
- Vault setup → Backup forms: offers restore (evidence: `src/screens/SetupScreen.tsx`)
- Vault screen → File manager UI: shows files (evidence: `src/screens/VaultScreen.tsx`)
- File manager UI → File API: manages files (evidence: `src/screens/FilesTab.tsx`)
- Backup forms → Backup API: restores backup (evidence: `src/components/RestoreBackupForm.tsx`)
- Vault API → Tauri API client: invokes commands (evidence: `src/api/vault.ts`)
- Security API → Tauri API client: invokes commands (evidence: `src/api/security.ts`)
- Backup API → Tauri API client: invokes commands (evidence: `src/api/backup.ts`)
- File API → Tauri API client: invokes commands (evidence: `src/api/files.ts`)
- Tauri API client → Tauri commands: dispatches invokes (evidence: `src/api/client.ts`)
- Tauri commands → Vault session: routes vault operations
- Tauri commands → Password entries: routes entry operations
- Tauri commands → Encrypted files: routes file operations
- Tauri commands → Encrypted backups: routes backup operations
- Vault session → Vault header: uses vault metadata (evidence: `src-tauri/src/vault/session.rs`)
- Vault session → SQLite storage: uses storage (evidence: `src-tauri/src/vault/session.rs`)
- Vault session → Cryptographic core: derives vault key (evidence: `src-tauri/src/vault/session.rs`)
- Password entries → SQLite storage: stores encrypted records
- Password entries → Cryptographic core: encrypts records
- Encrypted files → Cryptographic core: encrypts file chunks
- Encrypted backups → Cryptographic core: encrypts backup
- Security API → Lock and clipboard: requests lock services
- Lock and clipboard → Vault session: locks vault
