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 β
- Authentication Gate: Requests carry either a short-lived
api-Bearer token (session) or ansg_admin_sessioncookie (for/superlobster). - Schema Invariant Check: Zod validates all inputs before controllers execute.
- 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. - Forensic Auditing: Every mutation (create, edit, delete, backup, login) emits an asynchronous, redacted event to
audit.sqlite.