Whisp - Distributed Personal Knowledge Base

A peer-to-peer personal knowledge base that syncs bidirectionally across your devices in real-time without a central server. Built with BEAM (Elixir) for distributed systems and React for the frontend.

Features

• 🌐 Peer-to-Peer Mesh Network: No central server, devices connect directly
• 🔄 Real-Time Sync: Changes propagate instantly when devices are connected
• 📴 Offline-First: All data available locally, no internet required
• ⚡ CRDT-Based: Conflict-free replicated data types ensure eventual consistency
• 🔒 Privacy-Focused: Your data stays on your devices
• 🚀 BEAM-Powered: Leverages Erlang's distributed computing capabilities

Architecture

Backend (Elixir)

• Phoenix Framework: REST API and WebSocket server
• Distributed Erlang: Automatic node discovery and mesh networking
• Mnesia: Distributed replicated database
• CRDTs: Last-Write-Wins Register and Observed-Remove Set for conflict resolution
• libcluster: Gossip-based automatic node discovery
• Horde: Distributed process registry

Frontend (React + TypeScript)

• Vite: Fast development and optimized builds
• Zustand: Lightweight state management
• TypeScript: Type-safe development
• Heroicons: Beautiful UI icons

Getting Started

Prerequisites

• Elixir 1.15+ and Erlang/OTP 26+
• Node.js 18+ and npm
• Make (for convenience)

Installation

# Install all dependencies
make install

Development

# Start both backend and frontend
make dev

# Or start them separately:
make backend    # Backend on http://localhost:4000
make frontend   # Frontend on http://localhost:5173

The backend API will be available at http://localhost:4000/api and the frontend at http://localhost:5173.

Building for Production

# Build both backend and frontend
make build

Usage

Creating Notes

1. Click the + button in the sidebar
2. Start typing in the title and content fields
3. Changes are saved automatically
4. Add tags using the tag input at the bottom

Distributed Sync

Running Multiple Nodes

To test distributed sync, run multiple backend instances:

# Terminal 1 - Node 1
cd backend
NODE_NAME=whisp1@127.0.0.1 PORT=4000 make dev

# Terminal 2 - Node 2
cd backend
NODE_NAME=whisp2@127.0.0.1 PORT=4001 make dev

The nodes will automatically discover each other via gossip protocol and start syncing notes.

API Endpoints

• GET /api/notes - List all notes
• POST /api/notes - Create a note
• GET /api/notes/:id - Get a specific note
• PUT /api/notes/:id - Update a note
• DELETE /api/notes/:id - Delete a note
• GET /api/mesh/status - Get mesh network status
• GET /api/mesh/nodes - List connected nodes
• GET /health - Health check

Project Structure

Whisps/
├── backend/              # Elixir/Phoenix backend
│   ├── lib/
│   │   ├── whisp/       # Core business logic
│   │   │   ├── crdt/    # CRDT implementations
│   │   │   ├── mesh/    # Mesh networking
│   │   │   ├── storage/ # Mnesia storage
│   │   │   ├── sync/    # Sync engine
│   │   │   └── notes/   # Notes management
│   │   └── whisp_web/   # Web layer
│   │       ├── controllers/
│   │       └── channels/
│   ├── config/
│   ├── test/
│   └── Makefile
├── frontend/            # React frontend
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── store/       # Zustand stores
│   │   ├── lib/         # Utilities
│   │   └── types.ts     # TypeScript types
│   ├── public/
│   └── Makefile
├── ARCHITECTURE.md      # Detailed architecture docs
└── Makefile            # Root makefile

Development Commands

Root Level

make help       # Show available commands
make install    # Install dependencies
make dev        # Start dev servers
make build      # Build for production
make test       # Run tests
make clean      # Clean build artifacts

Backend

cd backend
make dev        # Start Phoenix server
make test       # Run tests
make format     # Format code
make compile    # Compile project
make shell      # Start IEx shell

Frontend

cd frontend
make dev        # Start Vite dev server
make build      # Build for production
make preview    # Preview production build
make format     # Format code

Configuration

Backend Configuration

Edit backend/config/runtime.exs:

# Node name and cookie
config :whisp,
  node_name: :whisp@127.0.0.1,
  cookie: :secret_cookie

# Cluster topology
config :libcluster,
  topologies: [
    whisp_gossip: [
      strategy: Cluster.Strategy.Gossip,
      config: [port: 45892, ...]
    ]
  ]

Frontend Configuration

Create frontend/.env:

VITE_API_URL=http://localhost:4000/api

Testing

# Backend tests
cd backend && make test

# Frontend tests (when configured)
cd frontend && make test

Deployment

Desktop App (Recommended)

Build as an Elixir release:

cd backend
mix release
./_build/prod/rel/whisp/bin/whisp start

Docker (Future)

Docker support coming soon for containerized deployment.

How It Works

1. CRDTs: Notes use Last-Write-Wins Registers for title/content and Observed-Remove Sets for tags
2. Vector Clocks: Track causality to detect concurrent updates
3. Mnesia Replication: Distributed database automatically replicates across nodes
4. Gossip Protocol: Nodes discover each other via UDP multicast
5. Phoenix PubSub: Real-time change propagation to connected clients
6. Offline Queue: Changes queued locally when offline, synced on reconnection

Contributing

Contributions welcome! Please read the architecture documentation first.

License

MIT

Acknowledgments

• Built with Phoenix Framework
• Inspired by Conflict-Free Replicated Data Types research
• Powered by the BEAM ecosystem