Whisper – Real-Time Secure Communication Terminal

📂 File Tree

├── backend
│   ├── app
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── extensions.py
│   │   ├── models.py
│   │   ├── repository.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   └── sockets.py
│   ├── .dockerignore
│   ├── Dockerfile
│   ├── main.py
│   └── requirements.txt
├── frontend
│   ├── src
│   │   ├── components
│   │   │   ├── KillSwitch.svelte
│   │   │   ├── MessageComposer.svelte
│   │   │   ├── MessageFeed.svelte
│   │   │   └── PassphraseModal.svelte
│   │   ├── services
│   │   │   ├── crypto.js
│   │   │   └── socket.js
│   │   ├── state
│   │   │   └── store.js
│   │   ├── App.svelte
│   │   └── main.js
│   ├── .dockerignore
│   ├── Dockerfile
│   ├── index.html
│   ├── package-lock.json
│   ├── package.json
│   └── vite.config.js
├── .dockerignore
├── .gitignore
├── Makefile
├── README.md
└── docker-compose.yml

🧩 Project Overview

Whisper is a secure, real-time messaging system designed for investigative teams needing fully encrypted communication.

• Messages are encrypted client-side; backend stores only ciphertext.
• Supports real-time broadcasting over WebSockets.
• Lightweight MVP designed to ship quickly under strict constraints.

⚡ Tech Stack & Choices

🛡 Kill Switch (Panic Mode)

• Activated by pressing ESC key 3 times consecutively.

• Actions on activation:

  1. Disconnects all Socket.IO connections immediately.
  2. Clears all local frontend state (messages, passphrase).
  3. Replaces UI with a generic 404 page or placeholder widget.

• No database wipe occurs — backend ciphertext is preserved.

• Implemented in frontend/src/components/KillSwitch.svelte + frontend/src/state/store.js.

🏗 Architecture

Browser
   │
   ▼
Nginx (frontend container)
   │
   ├── / → Svelte SPA
   │
   ├── /api → Flask REST backend
   │
   └── /socket.io → Flask-SocketIO

• Frontend connects to backend over internal Docker network.
• Backend broadcasts encrypted messages to all clients via Socket.IO.
• No server-side plaintext processing — fully blind relay.

🚀 Setup / Dev Instructions

Run everything in one command:

docker compose up -d --build

Endpoints:

• Frontend: http://localhost
• Backend Health: http://localhost/api/health
• Socket.IO: ws://localhost/socket.io/

Stop everything:

docker compose down

Remove persistent SQLite volume:

docker compose down -v

🔐 Security & Implementation Notes

• Shared Secret: Client asks for "Team Passphrase" → derives AES key.

• Message Encryption: All plaintext encrypted locally using AES + SHA256 passphrase via crypto-js.

• Frontend Simplicity:

  • No message bubbles, typing indicators, or extra colors.
  • Focused purely on secure messaging and Kill Switch functionality.

• Backend Logging: print() statements in sockets.py used instead of logging library.

• SQLite over Postgres: Chosen for lightweight dev MVP, avoids multi-container DB setup.

• REST API only: No GraphQL.

⚖ Trade-Off Analysis

📦 Docker Notes

• Backend Image: whisper-api
• Frontend Image: whisper-frontend
• Multi-stage builds reduce image size.
• Internal Docker network ensures frontend can reach backend via backend:5000.
• Volumes: whisper_data stores encrypted SQLite messages.

📝 Evaluation Criteria

• Security Hygiene: No plaintext storage on server; encryption isolated.

• Concurrency: Backend broadcasts messages without blocking; frontend appends efficiently.

• Architectural Integrity: Kill Switch works without exposing data.

• Code Quality: Clear separation:

  • Backend: Controller → Service → Repository
  • Frontend: View → State → Service