# debanganmali/obscura architecture

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

- Interactive diagram: https://gitdiagram.com/debanganmali/obscura
- Repository: https://github.com/debanganmali/obscura

## Overview

Obscura is a local-first password manager with a desktop interface and a CLI that operate on the same encrypted vault. The main workflow is choosing or creating a vault, unlocking its shared vault key, then managing and using entries; unlock methods include a master password, recovery code, Windows Hello, and passkeys. Major documented capabilities also include import/export, TOTP, password generation, clipboard handling, idle locking, and rollback detection. Some subsystem links rely on documented capabilities and the command surface; unsampled implementation details are not inferred.

Main entry points: [`src-tauri/src/commands.rs`](https://github.com/debanganmali/obscura/blob/main/src-tauri/src/commands.rs) (App commands), [`crates/obscura-vault/src/vault.rs`](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/vault.rs) (Vault and entries), [`crates/obscura-cli/src/main.rs`](https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/main.rs) (CLI entry point), [`ui/app.js`](https://github.com/debanganmali/obscura/blob/main/ui/app.js) (Desktop interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_web_ui["Desktop interface<br/>[app.js]"]
  node_tauri_commands["App commands<br/>[commands.rs]"]
  node_app_state["Session and idle lock<br/>[state.rs]"]
  node_watermark["Rollback watermark<br/>[watermark.rs]"]
  node_clipboard["Clipboard handling<br/>[clipboard.rs]"]
end

subgraph group_vault["Vault workflows"]
  node_vault_file[("Vault file")]
  node_vault_core["Vault and entries<br/>[vault.rs]"]
  node_entry_model["Entry model<br/>[entry.rs]"]
  node_format["Vault format<br/>[format.rs]"]
  node_csv_import["CSV import<br/>[csv_import.rs]"]
  node_portable["Encrypted export<br/>[portable.rs]"]
  node_totp["TOTP codes<br/>[totp.rs]"]
  node_generator["Password generator<br/>[generator.rs]"]
end

subgraph group_crypto["Cryptography"]
  node_crypto_api["Crypto primitives<br/>[lib.rs]"]
  node_kdf["Key derivation<br/>[kdf.rs]"]
  node_aead["Authenticated encryption<br/>[aead.rs]"]
  node_hybrid["Hybrid key wrapping<br/>[hybrid.rs]"]
end

subgraph group_unlock["Unlock methods"]
  node_recovery["Recovery codes<br/>[recovery.rs]"]
  node_hello["Windows Hello<br/>[hello.rs]"]
  node_passkey["Passkey support<br/>[lib.rs]"]
end

subgraph group_cli["Command line"]
  node_cli["CLI entry point<br/>[main.rs]"]
  node_cli_prompt["Credential prompt<br/>[prompt.rs]"]
  node_cli_tui["Terminal browser<br/>[tui.rs]"]
end

node_desktop_user(("Desktop user"))
node_authenticator(("Passkey authenticator"))
node_cli_user(("CLI user"))

node_desktop_user -->|"uses"| node_web_ui
node_web_ui -->|"invokes"| node_tauri_commands
node_tauri_commands -->|"manages vault"| node_vault_core
node_tauri_commands -->|"updates session"| node_app_state
node_app_state -->|"locks session"| node_tauri_commands
node_tauri_commands -->|"checks watermark"| node_watermark
node_tauri_commands -->|"copies secrets"| node_clipboard
node_vault_core -->|"reads and writes"| node_vault_file
node_vault_core -->|"encodes and decodes"| node_format
node_vault_core -->|"validates entries"| node_entry_model
node_vault_core -->|"derives unlock keys"| node_kdf
node_vault_core -->|"seals and opens"| node_aead
node_vault_core -->|"wraps recovery key"| node_hybrid
node_tauri_commands -->|"imports entries"| node_csv_import
node_tauri_commands -->|"exports entries"| node_portable
node_tauri_commands -->|"gets current code"| node_totp
node_tauri_commands -->|"generates password"| node_generator
node_tauri_commands -->|"creates recovery code"| node_recovery
node_tauri_commands -.->|"uses Hello unlock"| node_hello
node_tauri_commands -.->|"uses passkey unlock"| node_passkey
node_passkey -.->|"requests credential"| node_authenticator
node_cli_user -->|"runs commands"| node_cli
node_cli -->|"reads password"| node_cli_prompt
node_cli -->|"opens vault"| node_vault_core
node_cli -->|"browses vault"| node_cli_tui
node_cli_tui -->|"copies secrets"| node_clipboard

click node_web_ui "https://github.com/debanganmali/obscura/blob/main/ui/app.js"
click node_tauri_commands "https://github.com/debanganmali/obscura/blob/main/src-tauri/src/commands.rs"
click node_app_state "https://github.com/debanganmali/obscura/blob/main/src-tauri/src/state.rs"
click node_watermark "https://github.com/debanganmali/obscura/blob/main/src-tauri/src/watermark.rs"
click node_clipboard "https://github.com/debanganmali/obscura/blob/main/src-tauri/src/clipboard.rs"
click node_vault_core "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/vault.rs"
click node_entry_model "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/entry.rs"
click node_format "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/format.rs"
click node_csv_import "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/csv_import.rs"
click node_portable "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/portable.rs"
click node_recovery "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/recovery.rs"
click node_totp "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/totp.rs"
click node_generator "https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/generator.rs"
click node_crypto_api "https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/lib.rs"
click node_kdf "https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/kdf.rs"
click node_aead "https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/aead.rs"
click node_hybrid "https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/hybrid.rs"
click node_hello "https://github.com/debanganmali/obscura/blob/main/crates/obscura-platform/src/hello.rs"
click node_passkey "https://github.com/debanganmali/obscura/blob/main/crates/obscura-webauthn/src/lib.rs"
click node_cli "https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/main.rs"
click node_cli_prompt "https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/prompt.rs"
click node_cli_tui "https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/tui.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_web_ui,node_tauri_commands,node_app_state,node_watermark,node_clipboard,node_desktop_user,node_cli_user toneBlue
class node_vault_file,node_vault_core,node_entry_model,node_format,node_csv_import,node_portable,node_totp,node_generator toneAmber
class node_crypto_api,node_kdf,node_aead,node_hybrid toneMint
class node_recovery,node_hello,node_passkey toneRose
class node_cli,node_cli_prompt,node_cli_tui,node_authenticator toneIndigo
```

## Components

### Desktop app

- [Desktop interface](https://github.com/debanganmali/obscura/blob/main/ui/app.js): `ui/app.js`
- [App commands](https://github.com/debanganmali/obscura/blob/main/src-tauri/src/commands.rs): `src-tauri/src/commands.rs`
- [Session and idle lock](https://github.com/debanganmali/obscura/blob/main/src-tauri/src/state.rs): `src-tauri/src/state.rs`
- [Rollback watermark](https://github.com/debanganmali/obscura/blob/main/src-tauri/src/watermark.rs): `src-tauri/src/watermark.rs`
- [Clipboard handling](https://github.com/debanganmali/obscura/blob/main/src-tauri/src/clipboard.rs): `src-tauri/src/clipboard.rs`

### Vault workflows

- **Vault file**
- [Vault and entries](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/vault.rs): `crates/obscura-vault/src/vault.rs`
- [Entry model](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/entry.rs): `crates/obscura-vault/src/entry.rs`
- [Vault format](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/format.rs): `crates/obscura-vault/src/format.rs`
- [CSV import](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/csv_import.rs): `crates/obscura-vault/src/csv_import.rs`
- [Encrypted export](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/portable.rs): `crates/obscura-vault/src/portable.rs`
- [TOTP codes](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/totp.rs): `crates/obscura-vault/src/totp.rs`
- [Password generator](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/generator.rs): `crates/obscura-vault/src/generator.rs`

### Cryptography

- [Crypto primitives](https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/lib.rs): `crates/obscura-crypto/src/lib.rs`
- [Key derivation](https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/kdf.rs): `crates/obscura-crypto/src/kdf.rs`
- [Authenticated encryption](https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/aead.rs): `crates/obscura-crypto/src/aead.rs`
- [Hybrid key wrapping](https://github.com/debanganmali/obscura/blob/main/crates/obscura-crypto/src/hybrid.rs): `crates/obscura-crypto/src/hybrid.rs`

### Unlock methods

- [Recovery codes](https://github.com/debanganmali/obscura/blob/main/crates/obscura-vault/src/recovery.rs): `crates/obscura-vault/src/recovery.rs`
- [Windows Hello](https://github.com/debanganmali/obscura/blob/main/crates/obscura-platform/src/hello.rs): `crates/obscura-platform/src/hello.rs`
- [Passkey support](https://github.com/debanganmali/obscura/blob/main/crates/obscura-webauthn/src/lib.rs): `crates/obscura-webauthn/src/lib.rs`

### Command line

- [CLI entry point](https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/main.rs): `crates/obscura-cli/src/main.rs`
- [Credential prompt](https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/prompt.rs): `crates/obscura-cli/src/prompt.rs`
- [Terminal browser](https://github.com/debanganmali/obscura/blob/main/crates/obscura-cli/src/tui.rs): `crates/obscura-cli/src/tui.rs`

### Other components

- **Desktop user**
- **Passkey authenticator**
- **CLI user**

## Connections

- Desktop user → Desktop interface: uses
- Desktop interface → App commands: invokes
- App commands → Vault and entries: manages vault
- App commands → Session and idle lock: updates session
- Session and idle lock → App commands: locks session
- App commands → Rollback watermark: checks watermark
- App commands → Clipboard handling: copies secrets
- Vault and entries → Vault file: reads and writes
- Vault and entries → Vault format: encodes and decodes
- Vault and entries → Entry model: validates entries
- Vault and entries → Key derivation: derives unlock keys
- Vault and entries → Authenticated encryption: seals and opens
- Vault and entries → Hybrid key wrapping: wraps recovery key
- App commands → CSV import: imports entries
- App commands → Encrypted export: exports entries
- App commands → TOTP codes: gets current code
- App commands → Password generator: generates password
- App commands → Recovery codes: creates recovery code
- App commands → Windows Hello: uses Hello unlock
- App commands → Passkey support: uses passkey unlock
- Passkey support → Passkey authenticator: requests credential
- CLI user → CLI entry point: runs commands
- CLI entry point → Credential prompt: reads password
- CLI entry point → Vault and entries: opens vault
- CLI entry point → Terminal browser: browses vault
- Terminal browser → Clipboard handling: copies secrets