# Architecture Overview

This document describes the architecture and design rationale for the modular Rust system, including the `kvstore`, `vault`, and `evm_client` crates, as well as the CLI and WASM/web-app targets.

## Table of Contents
- [Summary](#summary)
- [Crate and Module Structure](#crate-and-module-structure)
- [Design Rationale](#design-rationale)
- [Vault Crate Design](#vault-crate-design)
- [Async, WASM, and Integration](#async-wasm-and-integration)
- [Diagrams & References](#diagrams--references)

---

## Summary
This system is organized as a Rust workspace with three core crates:
- `kvstore`: Abstract, async key-value storage for both native and WASM environments.
- `vault`: Manages encrypted keyspaces and cryptographic operations, using `kvstore` for persistence.
- `evm_client`: Ethereum RPC client, signs transactions using keys from `vault`.

Front-end targets:
- CLI (with Rhai scripting)
- WASM/web-app (with JS interop)

---

## Crate and Module Structure
- **Workspace:** Top-level `Cargo.toml` lists all member crates.
- **Features & cfg:** Use Cargo features and `#[cfg]` attributes for platform-specific code (e.g., `sled` for native, `idb` for WASM).
- **Dependencies:**
  - `kvstore` uses `sled` (native) and `idb` (WASM).
  - `vault` uses `kvstore` and crypto crates (`chacha20poly1305`, `pbkdf2`, etc.).
  - `evm_client` uses `vault` and Ethereum libraries (e.g., `alloy`).
  - CLI uses Rhai and async runtime (e.g., Tokio).
  - Web app uses `wasm-bindgen` and exposes Rust APIs to JS.

---

## Design Rationale
### Improvements in the New Implementation
- **Async/Await API:** All operations are async, supporting non-blocking I/O for both WASM and native environments.
- **Backend Abstraction:** The `KVStore` trait abstracts over multiple storage backends, enabling cross-platform support and easier testing.
- **Separation of Concerns:**
  - `kvstore` handles only storage.
  - `vault` is responsible for encryption, decryption, and password management.
- **WASM and Native Support:** Out-of-the-box support for both browser (IndexedDB) and native (sled) environments.
- **Cleaner, Testable Design:** Each layer is independently testable and mockable.

### Why Encryption and Password Protection are in Vault
- **Single Responsibility:** `kvstore` is for storage; `vault` handles security.
- **Flexibility:** Encryption algorithms and policies can evolve in `vault` without changing storage.
- **Security:** Cryptography is isolated in `vault`, reducing attack surface and easing audits.
- **Cross-Platform Consistency:** Same vault logic regardless of storage backend.

---

## Vault Crate Design
- **Encrypted Keyspace:** Password-protected, supports multiple keypairs (e.g., secp256k1, Ed25519).
- **Crypto APIs:** Async functions for key management, signing, encryption/decryption.
- **Storage:** Uses `kvstore` for persistence; re-encrypts and stores the keyspace as a blob.
- **WASM Compatibility:** Uses Rust crypto crates that support `wasm32-unknown-unknown`.

---

## Async, WASM, and Integration
- **Exports:** Use `#[wasm_bindgen]` to expose async functions to JS.
- **Async runtime:** Use `wasm_bindgen_futures::spawn_local` in the browser.
- **Interop:** JS and Rust communicate via Promises and `JsValue`.
- **CLI:** Uses Rhai scripting and async runtime.

---

## Diagrams & References
- See included diagrams for crate relationships and message-passing patterns.
- Design patterns and best practices are drawn from Rust async and WASM guidelines.

---

*This document merges and replaces content from the previous `Architecture.md` and `kvstore-vault-architecture.md`. For further details on implementation, see `vault_impl_plan.md`.*