PromptVault

Your personal, private library for AI prompts - organised, rated, and always at hand.

🧩 Install on Microsoft Edge  •  🚀 Launch Live Web App  •  📖 Architecture & Docs Portal  •  🗺️ 300% DPI Architecture Diagrams  •  🔒 Zero-Knowledge Security

[!IMPORTANT] [Community Edition] This public repository contains the open-source community core of PromptVault.

The live cloud platform (promptvault.multihat.dev), browser extension builds, and advanced Pro features (GitHub-style Version Control, Visual Diffs, and Multi-Tier Cloud Sync) are powered by the PromptVault MAX Engine.

📋 Table of Contents

• Comprehensive Architectural & Feature Synthesis
  • Architectural Breakdown
  • Visual Architecture & System Models (300% DPI)
  • Docs-as-Code Technical Documentation Portal
• What is PromptVault?
• What Can It Do? (Features)
  • Browser Extension (Edge & Chromium)
• How Does It Compare?
• Requirements
• Getting Started (Step by Step)
  • Step 1 - Download & Install
  • Step 2 - Configure API Keys
  • Step 3 - Start the App
  • Optional: Cloud Sync (Supabase)
• Deployment (Production)
  • Updating on a Droplet / VPS
• Security & Privacy
  • Privacy Policy & Zero Prompt Tracking
• Available Commands
• Contributing & Community
• License & Attribution

🏛️ Comprehensive Architectural & Feature Synthesis

PromptVault is a privacy-first, client-encrypted AI prompt workbench and local library built with an offline-first architecture, an integrated AI Librarian (powered by Google Gemini with multi-key pooling and Groq fallback), dynamic {{variable}} template injection, multi-device cloud synchronization via Supabase, and real-time usage analytics.

Architectural Breakdown

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                                 PROMPTVAULT ECOSYSTEM                                   │
├──────────────────────────────────────┬──────────────────────────────────────────────────┤
│ 🎨 Frontend (Client-Side)            │ 🔒 Cryptography & Storage Layer                 │
│ • React 19 + TypeScript 5.8 (Strict) │ • AES-256-GCM on-device encryption               │
│ • Tailwind CSS v4 + Motion           │ • PBKDF2-SHA-256 KDF (600,000 iterations)        │
│ • Virtualized Grid (>200 items)      │ • 6-digit PIN entropy + Emergency Recovery Key   │
│ • Offline PWA + Pre-paint Theme Init │ • Active session memory zeroing on manual lock   │
│ • Active theme preservation on lock  │ • Guarded localStorage with quota-aware error    │
├──────────────────────────────────────┼──────────────────────────────────────────────────┤
│ 🧠 AI Librarian Proxy Server         │ ☁️ Cloud Sync & Data Resilience                 │
│ • Express + TypeScript proxy         │ • Supabase PostgreSQL backend with Google OAuth  │
│ • Dual-Provider: Gemini + Groq       │ • Per-Entity LWW merge with 30-day tombstones    │
│ • Multi-Key Pool with 429 Cooldown   │ • Conflict-free cross-device synchronization     │
│ • SHA-256 LRU Cache & Coalescing     │ • JSON Import/Export with Schema Sanitization    │
└──────────────────────────────────────┴──────────────────────────────────────────────────┘

Visual Architecture & System Models (300% DPI)

PromptVault includes a comprehensive visual library of super-ultra-high-quality architectural models rendered at 300% DPI (3x scale factor) in the diagrams/ directory:

Diagram Model	Focus Area	Resolution
System Architecture	End-to-end 4-tier topology spanning Client, AI Gateway, LLM Providers, and Cloud Sync	2352 x 6744 px
Cryptographic Workflow	PBKDF2 derivation, 256-bit DEK generation, AES-256-GCM sealing, and 6-digit PIN / Passphrase unlocking	2352 x 10482 px
Cloud Sync Lifecycle	1-second debounced push, 30-second silent poll, LWW merge engine, and 30-day tombstone cleanup	2352 x 17904 px
AI Suggestion Pipeline	Gemini multi-key pooling, Groq automatic circuit-breaker fallback, in-flight coalescing, and caching	2352 x 25248 px
Runtime Workflows	Smart template substitution, AI Prompt Doctor evaluation and rewriting, and portable JSON backup	2256 x 17973 px

Figure 1: High-level System Architecture topology. Click the image to view the full 300% DPI high-resolution diagram.

Docs-as-Code Technical Documentation Portal

PromptVault features a complete, enterprise-grade technical documentation suite authored under the Docs-as-Code standard in docs/:

What is PromptVault?

If you use AI tools like ChatGPT, Gemini, or Claude, you've probably written some really good instructions (called "prompts") that get great results - and then lost them. They end up buried in chat history, scattered across notes apps, or simply forgotten.

PromptVault is a personal library for those prompts. Think of it like a recipe book, but instead of cooking instructions, it stores your best AI instructions. You can:

• Save prompts with a title, category, and tags so you can find them again
• Rate and improve them using a built-in AI assistant
• Copy any prompt to your clipboard in one click, ready to paste into any AI tool
• Access everything privately, from any device, without handing your data to a third party

Everything is stored directly in your browser. No sign-up required. No ads. No data sharing. You own your vault.

What Can It Do?

🔒 Encrypt Your Vault

You can encrypt the local vault with either a numeric PIN (minimum 6 digits for new vaults, 4 digits for legacy unlocks) or a passphrase (minimum 15 characters, recommended by default). PromptVault uses AES-256-GCM for vault data, PBKDF2-SHA-256 (600,000 iterations) to derive the key that unlocks it, and progressive cooldown delays after consecutive failed unlock attempts. Your secret is never stored. A PIN is convenient for local devices, but a long passphrase provides the highest cryptographic resistance against offline guessing. Save the one-time recovery key shown during setup.

• Active Session Memory Hygiene: When you manually lock your vault, decrypted prompt data in React state and internal memory references is immediately cleared and zeroed out. Open edit dialogs and modal overlays are automatically closed to prevent UI data leakage.
• Defensive Storage Guard: Storage write handlers guard against accidental unencrypted data persistence while the vault is locked.
• Theme Setting Preservation: Your active dark or light theme preference is preserved across locking, unlocking, and recovery cycles.

🤖 Built-In AI Assistant

Not sure if your prompt is well-written? The AI Librarian can:

• Score it out of 10 and explain what's weak
• Rewrite it into a better, more effective version
• Suggest a title, category, and tags so you don't have to think about filing

The AI assistant works privately through a backend service - your API keys are never exposed to the browser.

📂 Organise by Category

Create your own folders (called categories) - things like Coding, Marketing, Writing, or whatever fits your workflow. Rename or delete them any time. Each category shows a count of how many prompts it contains.

⭐ Favourites & Search

Star your most-used prompts so they're always one click away. A full-text search bar lets you find any prompt by its title, content, or tags - instantly, with no loading.

📊 Usage Statistics

A built-in dashboard shows you which prompts you use most, how active your library is, and your top categories - so you can see what's actually working in your workflow.

🔄 Fill-in-the-Blank Templates

Write a prompt once with placeholders like {{topic}} or {{audience}}. When you copy it, PromptVault will ask you to fill in each blank before putting it on your clipboard. Great for prompts you reuse with small variations every time.

💾 Backup & Restore

Export your entire vault as a single file at any time. If you ever switch devices or browsers, just import the file and everything is back instantly.

☁️ Optional Cloud Sync

If you want your prompts available on multiple devices (your laptop and phone, for example), you can sign in with Google. Your vault will stay in sync automatically. This is entirely optional - the app works perfectly without it.

🌗 Light & Dark Mode

Switch between a dark theme (easy on the eyes at night) and a light theme (great in sunlight). Your preference is remembered.

📱 Works on Mobile Too

The app is fully usable on phones and tablets. The sidebar slides in and out, buttons are large enough to tap, and the layout adjusts to any screen size.

🧩 Browser Extension (Microsoft Edge & Chromium)

PromptVault is officially available on the Microsoft Edge Add-ons Store (compatible with Microsoft Edge and Chromium browsers). It brings your encrypted prompt vault directly into your daily AI workflows:

Figure: Official PromptVault listing on the Microsoft Edge Add-ons Store (Version 2.3.1). Click the screenshot to open the live store page.

• Official 1-Click Store Installation: Install directly from the Microsoft Edge Add-ons Store with automatic background updates (Store ID: 0RDCK9QZNVBV, Extension ID: ckhifhpbhebgnfomgcojfakpampkijni).
• In-Chat Quick Picker Overlay (Alt+P): Press Alt+P (or Option+P on Mac) inside ChatGPT, Claude, Google Gemini, DeepSeek, Perplexity, or any webpage to search and inject prompts into the active chat box in one click. Isolated inside a shadow DOM to ensure host CSS isolation.
• In-Chat Command Trigger (/pv): Type /pv directly inside any AI chat input to open an instant prompt suggestion picker without moving your hands from the keyboard.
• 1-Click Web Clipping: Select any text on any webpage, right-click, and choose Save selection to PromptVault to store prompt snippets directly into your vault.
• Offline-First AES-256-GCM Security: All prompts stay encrypted on your local machine using hardware-backed Web Crypto APIs.
• Optional Multi-Device Cloud Sync: Sign in with Google via chrome.identity to sync your encrypted prompt library across multiple computers with Supabase.

How Does It Compare?

Why choose PromptVault instead of saving prompts in a general note-taking app or on a cloud prompt directory? Here is how it compares across key developer and privacy needs:

What Do You Need to Run It?

PromptVault is a web application you run on your own computer (or server). It is not a hosted service - you install and run it yourself, which is what makes it private.

To get started you need two things:

1. Node.js (version 20 or newer) - a free program that lets your computer run JavaScript applications. Download it here.

2. At least one AI API key - a free-to-obtain password that lets PromptVault connect to an AI service on your behalf. You need one of:

   • Google Gemini - Get a free key here (generous free tier)
   • Groq - Get a free key here (very fast, free tier)

   PromptVault tries Gemini first and automatically falls back to Groq if it's unavailable. Your keys stay on your own server and are never sent to the browser.

Getting Started (Step by Step)

Step 1 - Download the project and install dependencies

Open a terminal (Command Prompt on Windows, Terminal on Mac/Linux) and run:

git clone https://github.com/SagarBiswas-MultiHAT/promptVault.git
cd promptVault
npm install

What does this do? It downloads the project files to your computer and installs all the helper packages it depends on (including vite, tsx, and all other tools used to run the app).

⚠️ npm install is required before anything else. If you skip this step and try to run the app, you'll see errors like 'vite' is not recognized or 'tsx' is not recognized. Run npm install once and they will go away.

Step 2 - Add your API keys

Copy the example settings file:

Mac / Linux:

cp .env.example .env

Windows (Command Prompt or PowerShell):

copy .env.example .env

Then open the newly created .env file in any text editor (Notepad works fine) and fill in your keys:

GEMINI_API_KEYS="paste-your-gemini-key-here"
GROQ_API_KEY="paste-your-groq-key-here"

What is .env? It's a plain text file that holds private settings for the app - like passwords. It stays on your computer and is never uploaded anywhere.

💡 Verify your keys: Run npm run test:keys to check that all your keys are authenticated and working. See the API Key Diagnostic Guide for full details.

Step 3 - Start the app

Before running these commands, make sure you have completed Step 1 (npm install). If you see errors like 'vite' is not recognized or 'tsx' is not recognized, it means the install step was skipped - go back and run npm install first.

You need two terminal windows open at the same time. In the first, run:

npm run dev:api

In the second, run:

npm run dev

Then open your browser and go to http://localhost:3000. PromptVault will be running.

Why two terminals? One runs the AI assistant service in the background (the part that talks to Gemini/Groq). The other runs the visual app you see in your browser. Both need to be running at the same time.

Optional: Enable Cloud Sync

If you want your vault to stay in sync across multiple devices, you can connect a free Supabase account. Supabase is a free, open-source service that securely stores your data in the cloud.

1. Create a free account at supabase.com and start a new project.
2. In your Supabase project, go to Authentication → Providers and enable Google.
3. Add http://localhost:3000 to your list of allowed redirect URLs (under Authentication → URL Configuration).
4. Go to the SQL Editor in Supabase and run this script to create the storage table:

create table public.vaults (
  user_id uuid primary key references auth.users(id) on delete cascade,
  data jsonb not null,
  schema_version text not null,
  updated_at timestamptz not null default now()
);

alter table public.vaults enable row level security;

create policy "Users can view own vault"
on public.vaults for select
using (auth.uid() = user_id);

create policy "Users can insert own vault"
on public.vaults for insert
with check (auth.uid() = user_id);

create policy "Users can update own vault"
on public.vaults for update
using (auth.uid() = user_id)
with check (auth.uid() = user_id);

create policy "Users can delete own vault"
on public.vaults for delete
using (auth.uid() = user_id);

1. Copy your Project URL and anon public key from Supabase → Project Settings → API, then add them to your .env file:

VITE_SUPABASE_URL="https://your-project.supabase.co"
VITE_SUPABASE_ANON_KEY="your-anon-key"

Once set up, you'll see a "Sign in with Google" button in the app. After signing in, your vault syncs automatically.

Putting It on the Internet (Deployment)

If you want to access PromptVault from anywhere - not just your own computer - you can deploy it to a hosting service. This means running it on a server that's always on and reachable from any browser.

Step 1 - Build the app for production

npm run build
npm start

This packages all the app files into an optimised bundle and starts a single server that handles everything. The server runs on port 3002 by default.

Step 2 - Choose a hosting platform

Any platform that runs Node.js applications will work. Popular options:

Step 3 - Set your environment variables on the platform

Every hosting platform has a place to enter secret settings (the equivalent of your .env file). You'll need to enter these:

The two VITE_ settings behave differently from the rest. They are read by the bundler and written into the JavaScript files during npm run build, so they must be set before the platform runs its build command - and if you ever change one, restarting the server is not enough. You have to rebuild and redeploy. Everything else in the table is read by the server at startup, so a restart is sufficient for those.

Important: When you deploy to a real domain, you'll also need to update the social sharing links inside index.html - specifically the og:url, og:image, twitter:image, and canonical lines - to point to your actual domain name.

🔄 Updating Your Project on a Droplet / VPS

When you push new commits to GitHub and want to update your live DigitalOcean Droplet (or any Linux VPS), follow these steps:

1. Connect to your Droplet

ssh root@your-droplet-ip

2. Navigate to your project directory

cd /var/www/promptvault

3. Pull the latest changes, rebuild, and restart

Step-by-step:

# 1. Pull the latest commits cleanly (avoids accidental local merge conflicts)
git pull --ff-only origin main

# 2. Clean install dependencies strictly from package-lock.json
npm ci

# 3. Rebuild the frontend bundle (Vite injects VITE_* variables here)
npm run build

# 4. (Optional) Run zero-token API key health check on the server
npm run test:keys

# 5. Restart PM2 with fresh environment variables and persist the process state
pm2 restart promptvault --update-env
pm2 save

⚡ All-in-one bulletproof update command:

cd /var/www/promptvault && git pull --ff-only origin main && npm ci && npm run build && pm2 restart promptvault --update-env && pm2 save

4. Verify deployment health

pm2 status
pm2 logs promptvault --lines 20

💡 Browser Cache & Service Worker Notice: PromptVault is a PWA. If you do not see the newest UI updates immediately after deploying:

1. Open https://promptvault.multihat.dev (or your domain).
2. Press F12 → Application → Service Workers → click Unregister.
3. Perform a hard refresh (Ctrl + Shift + R or Cmd + Shift + R).

Is My Data Safe?

Yes. Here's how PromptVault protects you:

Available Commands

Run these in your terminal from the project folder:

Contributing & Community

PromptVault is an open-source project built for the AI community, and we welcome contributors of all skill levels.

• Getting Started: Read our Contributing Guide for local setup, development commands, and pull request guidelines.
• Documentation Portal: Explore the full Architecture & Engineering Documentation for C4 models, ERDs, and ADRs.
• Security Inquiries: Review our Security Policy for responsible vulnerability disclosure and threat model details.
• Join the Discussion: Visit our GitHub Discussions to share your favorite prompt workflows, propose ideas, or ask questions.
• Good First Issues: Explore issues labeled good first issue on GitHub for well-scoped starter contributions.
• Version History: See CHANGELOG.md for a complete record of releases and changes.

⭐ Star History & Community Support

If you find PromptVault useful for your AI workflow or project, please consider giving this repository a star on GitHub! It helps more developers discover the project and keeps development active.

License & Attribution

PromptVault is licensed under the Apache License, Version 2.0.

In accordance with Section 4(d) of the Apache License 2.0, any fork, redistribution, or hosted deployment of this application must retain the root NOTICE file and maintain visible attribution to Sagar Biswas (@SagarBiswas-MultiHAT) within both the documentation and the user interface.

Cloning this repository, stripping .git commit history, removing copyright or NOTICE files, or misrepresenting this codebase as your own original work is a direct violation of the license and international copyright law, and will result in an immediate GitHub DMCA Takedown notice.