Architecture Overview

Comprehensive technical documentation of the haex-vault architecture, components, and how they work together.

System Overview

haex-vault is a Tauri-based desktop and mobile application that serves as a secure host for extensions (haextensions). The architecture is designed around three core principles: offline-first operation, end-to-end encryption, and extensibility.

┌─────────────────────────────────────────────────────────────────┐
│                         haex-vault                               │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Vue 3 Frontend                            │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │ │
│  │  │   Stores    │  │ Composables │  │     Components      │  │ │
│  │  │  (Pinia)    │  │  (Handlers) │  │    (Nuxt UI)        │  │ │
│  │  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │ │
│  └─────────┼────────────────┼────────────────────┼─────────────┘ │
│            │                │                    │               │
│            └────────────────┼────────────────────┘               │
│                             │ Tauri IPC                          │
│  ┌──────────────────────────┴──────────────────────────────────┐ │
│  │                    Tauri Backend (Rust)                      │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │ │
│  │  │    CRDT     │  │  Extension  │  │     Database        │  │ │
│  │  │   Engine    │  │   Runtime   │  │  (SQLite/SQLCipher) │  │ │
│  │  └──────┬──────┘  └─────────────┘  └──────────┬──────────┘  │ │
│  └─────────┼─────────────────────────────────────┼─────────────┘ │
└────────────┼─────────────────────────────────────┼───────────────┘
             │                                     │
             │ HTTPS/WSS                           │ Encrypted
             ▼                                     ▼
┌─────────────────────────┐              ┌─────────────────────────┐
│    haex-sync-server     │              │    Local SQLite DB      │
│  (Supabase/PostgreSQL)  │              │   (Encrypted Vault)     │
└─────────────────────────┘              └─────────────────────────┘

The application consists of a Vue 3 frontend communicating with a Rust backend through Tauri's IPC layer. All user data is stored in an encrypted SQLite database using SQLCipher, with CRDT-based synchronization to the cloud.

Technology Stack

haex-vault uses a modern tech stack optimized for security, performance, and developer experience.

Frontend

Vue 3 + TypeScript
Nuxt UI Components
Pinia State Management
Drizzle ORM

Backend (Rust)

Tauri (Rust)
SQLite + SQLCipher
CRDT Sync Engine
Extension Runtime

Sync Server

Supabase (PostgreSQL)
Realtime Subscriptions
Column-Level HLC
E2E Encryption

Extensions

iframe/WebView Sandbox
haex-vault-sdk
Permission System
Hot Reload (Dev)

Repository Structure

The haex ecosystem consists of multiple repositories, each with a specific responsibility.

haex-vault

Main application - Desktop/Mobile client

Tauri + Vue

haex-sync-server

Sync backend with Supabase/PostgreSQL

Hono + Supabase

haex-marketplace

Extension marketplace and distribution

Hono + Supabase

haex-vault-sdk

SDK for extension developers

TypeScript

haex-space

haex.space website and documentation

Nuxt

Project Structure

The main haex-vault repository follows a standard Tauri project structure with additional organization for the CRDT sync system and extension runtime.

haex-vault/
├── src/                      # Vue Frontend
│   ├── components/           # Vue Components (Nuxt UI)
│   ├── stores/               # Pinia Stores
│   │   ├── vault/            # Vault Management
│   │   ├── sync/             # Sync Engine & Orchestrator
│   │   │   ├── orchestrator/ # Push/Pull/Realtime Logic
│   │   │   ├── engine.ts     # Key Management
│   │   │   ├── backends.ts   # Backend Configuration
│   │   │   └── syncEvents.ts # Event Bus for Updates
│   │   └── extensions/       # Extension Store
│   ├── composables/          # IPC Handlers & Utilities
│   │   └── handlers/         # Tauri Command Wrappers
│   ├── database/             # Drizzle Schemas
│   └── utils/crypto/         # Encryption Utilities
├── src-tauri/                # Rust Backend
│   ├── src/
│   │   ├── crdt/             # CRDT Implementation
│   │   │   ├── commands.rs   # Tauri Commands
│   │   │   ├── trigger.rs    # SQL Trigger Generation
│   │   │   └── hlc.rs        # Hybrid Logical Clock
│   │   ├── extension/        # Extension Runtime
│   │   │   ├── core/         # Manager, Manifest, Protocol
│   │   │   ├── database/     # SQL Execution & Validation
│   │   │   ├── permissions/  # Permission Enforcement
│   │   │   └── webview/      # Multi-Window Management
│   │   ├── database/         # SQLite Connection & Migrations
│   │   └── lib.rs            # Tauri Command Registration
│   └── migrations/           # SQL Migrations
└── .claude/                  # Knowledge Database

Data Flow

Data flows through the system in a predictable pattern, from user interaction through the sync layer.

User Action → Vue Component → Pinia Store → Tauri IPC → Rust Backend → SQLite

User Interaction

User interacts with Vue components. Changes are dispatched to Pinia stores.

IPC Communication

Stores call Tauri commands through composable handlers. Data is serialized for IPC.

Rust Processing

Rust backend validates, encrypts, and stores data in SQLite. CRDT triggers fire.

Sync Orchestration

Sync orchestrator detects changes and pushes to cloud. Other devices receive realtime updates.

Security Architecture

Security is built into every layer of the haex-vault architecture.

Encrypted Storage

All user data is stored in SQLCipher-encrypted SQLite databases. The encryption key is derived from the user's vault password using PBKDF2.

Two-Password System

haex-vault uses separate passwords for local encryption and server authentication:

Vault Password: Encrypts the local SQLite database and sync key
Server Password: Authenticates with the sync server (Supabase Auth)

End-to-End Encryption

All data synced to the cloud is encrypted with the vault key before leaving the device. The sync server never sees plaintext data.

←Introduction Sync & CRDT→