Jannis Braun
06c538b013
Companion to #29. `healInitialSchemaDrift` can only ADD columns, so it skips NOT NULL-without-default columns like `federation_outbox.entity_id` / `context_id` — which on some old pre-drizzle dev DBs carry the pre-rename names `message_id` / `dm_channel_id` instead. The tables load but the outbox worker fails every tick with "no such column: federation_outbox.context_id" once the server is up. Adds healRenamedColumns() — a second pass that runs right after `healInitialSchemaDrift`. For each table whose physical column set is *missing* columns declared by the current-migration-state snapshot AND which holds zero rows, it DROPs the table and rebuilds it from the snapshot's JSON: columns, defaults, foreign keys, composite PKs, unique constraints, indexes. Key design decisions: - **Target is the current-migration-state snapshot, not the latest on disk.** The current state is determined by the highest `__drizzle_migrations.created_at` matched against `_journal.json`'s `when` timestamps (with backward walk for idx values that lack a snapshot, like the hand-written 0002). Rebuilding to a *future* snapshot would introduce columns that drizzle's migrator is about to add via ALTER TABLE ADD COLUMN, causing duplicate-column errors. Rebuilding to the *current* snapshot preserves the invariant that drizzle's pending migrations can run cleanly afterwards. - **Missing-column gate, not extra-column.** Extra columns alone don't break anything at runtime (the ORM ignores them); they're leftover from pre-drizzle manual migrations and might matter to the operator. Missing columns DO break runtime queries, so only those trigger rebuild. - **Empty-table gate.** Non-empty tables log a warning and skip — data preservation wins over heal, and this path should only ever hit a pre-drizzle dev DB that never exercised the affected tables in the first place. - **Transactional rebuild.** DROP + CREATE + index reinstatement wrap in a single `db.transaction()` so a partial rebuild rolls back. Verified against three scenarios via in-memory simulation: (A) fresh install — heal no-op, drizzle creates everything; (B) pre- drizzle dev DB with fed_outbox/fed_mutation_log rename drift — tables rebuilt to 0000 snapshot, drizzle then applies 0001–0004 successfully to reach the current target schema; (C) post-migration- correct (production-like) — heal no-op, drizzle no-op, schema unchanged. Live boot on my actual dev DB: migrations complete silently, server binds :3005, no outbox worker errors. Server tests 110/110, web 131/131, typecheck clean. No migration files changed. Deployed Pi+VM instances are unaffected (their schema matches the snapshot exactly — heal won't touch anything). Closes backlog #30.
Backspace
Open-source, self-hosted Discord alternative built with TypeScript.
Features
- Real-time text messaging with WebSocket
- Servers, channels, and role-based permission management
- Voice and video chat via LiveKit
- Screen sharing with configurable quality (VP9)
- Direct messages (1-on-1 and group DMs up to 10)
- DM voice/video calls with ringing
- Friend system with requests
- File uploads and image sharing
- Markdown message formatting with syntax highlighting
- Message reactions, replies, and editing
- Typing indicators, presence status, and read states
- Invite system with shareable codes
- Instance-level admin panel (streaming limits)
- Desktop app (Electron)
- Mobile-responsive web UI
- Docker deployment
Tech Stack
| Layer | Technology |
|---|---|
| Backend | Fastify + TypeScript |
| Database | SQLite (better-sqlite3) + Drizzle ORM |
| Auth | JWT + bcrypt |
| Real-time | WebSocket (ws) |
| Frontend | React 18 + Tailwind CSS + Zustand |
| Voice/Video | LiveKit |
| Desktop | Electron |
| Build | Vite + pnpm workspaces |
Quick Start with Docker
# Clone the repository
git clone https://github.com/your-username/backspace.git
cd backspace
# Create environment file
cp .env.example .env
# Generate a JWT secret
echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env
# Start Backspace
docker compose up -d
Open http://localhost:3000 in your browser. A default server "Backspace" is created automatically.
Default admin account: admin / admin123 (change this after first login).
Development Setup
Prerequisites
- Node.js 20+
- pnpm 8+
Install
pnpm install
Configure
cp .env.example .env
# Edit .env with your settings (generate a JWT_SECRET)
Run
# Start both server and web dev server
pnpm dev
# Or start individually
pnpm dev:server # API server on :3005
pnpm dev:web # Vite dev server on :5173
Build
pnpm build
This builds the shared types, server, and web frontend. The server serves the built frontend in production mode.
Project Structure
Backspace/
├── packages/
│ ├── shared/ # Shared TypeScript types & permissions
│ ├── server/ # Fastify API + WebSocket server
│ ├── web/ # React frontend (Vite + Tailwind)
│ └── desktop/ # Electron desktop app
├── data/ # SQLite DB + uploads (created at runtime)
├── Dockerfile
├── docker-compose.yml
└── .env.example
Voice & Video
Voice and video requires a LiveKit server. Set these in your .env:
LIVEKIT_URL=wss://your-livekit-server
LIVEKIT_API_KEY=your-api-key
LIVEKIT_API_SECRET=your-api-secret
Without LiveKit configured, text chat works fully but voice/video channels will not connect.
API
The server exposes a REST API and WebSocket endpoint:
- REST API:
http://localhost:3000/api/* - WebSocket:
ws://localhost:3000/ws - Health check:
GET /api/health
See CLAUDE.md for the full API reference.
Desktop App
The Electron desktop app wraps the web UI and adds system tray, notifications, and native window controls.
cd packages/desktop
pnpm build:ts # Compile TypeScript
pnpm dev # Run in development
pnpm build # Package for distribution
License
MIT