Skip to content

System Architecture Overview ​

ShellGuard is architected as a lightweight, single-binary container deployment that unifies a React 19 frontend and an Express 5 backend over an encrypted SQLite bedrock.


πŸ›οΈ System Blueprint ​

text
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                            CLIENT BROWSER                                   β”‚
β”‚                                                                             β”‚
β”‚  React 19 SPA (Vite) Β· Tailwind CSS Β· Framer Motion                         β”‚
β”‚  β”œβ”€ ShellCryption Engine (HKDF-SHA-256 + AES-GCM-256)                       β”‚
β”‚  β”œβ”€ Key Derivation & In-Memory Key Cache                                    β”‚
β”‚  β”œβ”€ TOTP Generation & Authenticator Engine                                  β”‚
β”‚  └─ Dynamic Router (/superlobster, /admin-login, /)                         β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                       β”‚ HTTPS / JSON Payloads
                                       β”‚ (Client-Sealed Blobs)
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                        EXPRESS 5 API SERVER (:6565 / :6464)                 β”‚
β”‚                                                                             β”‚
β”‚  Middleware Pipeline:                                                       β”‚
β”‚  β”œβ”€ Helmet & CORS Policy                                                    β”‚
β”‚  β”œβ”€ Cookie Parser (sg_admin_session)                                        β”‚
β”‚  β”œβ”€ Rate Limiters (5/10m Admin, 10/15m Auth, Per-Agent Burst Controls)      β”‚
β”‚  β”œβ”€ Zod & Busboy Streaming (500 MB attachment ceiling, 1000 MB quota)        β”‚
β”‚  β”œβ”€ Per-Row Metadata Encryption Filter (prepareReadAll / prepareWrite)      β”‚
β”‚  └─ Error Handler (Production masking, SQLITE_BUSY retry)                   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                       β”‚ Direct Driver Calls
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                    SQLITE STORAGE BEDROCK (WAL MODE)                        β”‚
β”‚                                                                             β”‚
β”‚  better-sqlite3-multiple-ciphers                                            β”‚
β”‚  β”œβ”€ DATA_DIR/db.sqlite (SQLCipher Layer 3 At-Rest Encryption)               β”‚
β”‚  β”œβ”€ DATA_DIR/audit.sqlite (Append-Only Forensic Reef)                       β”‚
β”‚  └─ DATA_DIR/backups/ (Online Backup API Atomic Snapshots)                  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

🌊 Request Lifecycle ​

  1. Authentication Gate: Requests carry either a short-lived api- Bearer token (session) or an sg_admin_session cookie (for /superlobster).
  2. Schema Invariant Check: Zod validates all inputs before controllers execute.
  3. Metadata Encryption: On POST/PUT, metadata fields (title, URL, username, notes, category, tags) are encrypted with server-side AES-256-GCM before writing to SQLite.
  4. Forensic Auditing: Every mutation (create, edit, delete, backup, login) emits an asynchronous, redacted event to audit.sqlite.

Read More ​

Sovereign Zero-Knowledge Secrets Vault. Released under AGPL-3.0. β€’ Privacy Policy