Family Ledger

Shared expense tracker built with Svelte 5 + SpacetimeDB.

Log expenses, split costs, settle debts — all in real-time across devices. Includes an AI chat assistant that understands your family's finances.

Stack

• Frontend: Svelte 5 + Vite + TypeScript
• Backend: SpacetimeDB (real-time database with server-side logic)
• AI Chat: AIMLAPI (Grok 4, streaming SSE)
• Desktop: Neutralino (optional, lightweight native shell)

Quick Start

1. Set up SpacetimeDB

Create a free account at spacetimedb.com, then:

# Install the CLI
npm install -g @clockworklabs/spacetimedb-sdk

# Publish the module (pick your own name)
cd module/spacetimedb
npm install
npm run build
spacetime publish your-ledger-name

2. Configure the frontend

cd client
cp .env.example .env

Edit .env with your module name and (optionally) an AI API key:

VITE_STDB_MODULE=your-ledger-name
VITE_AI_API_KEY=your-api-key-here

3. Run it

npm install
npm run dev

Open localhost:5173, pick a nickname, and start logging expenses.

Features

• Real-time sync — Changes appear instantly across all connected browsers
• Split methods — Equal, exact amounts, or percentage-based splits
• Balance tracking — See who owes whom at a glance
• Activity feed — Every action logged as an event
• AI chat — Ask "who owes whom?" or "summarize our spending" (requires API key)
• Integer math — All currency in cents, never floats (no rounding bugs)
• Digital root flags — Vedic O(1) pattern detection on expense amounts

Project Structure

client/               Svelte 5 frontend
  src/
    App.svelte        Main app (4 views: Expenses, Settle, Events, Chat)
    lib/db.ts         SpacetimeDB connection + reactive stores
    lib/utils.ts      Utilities (digitalRoot, formatCents, timeAgo)
    lib/ai.ts         AI chat client (streaming SSE)
    module_bindings/  Auto-generated STDB TypeScript types

module/               SpacetimeDB backend
  spacetimedb/
    src/index.ts      Tables, reducers, and server-side logic

desktop/              Neutralino desktop wrapper (optional)

docs/                 Documentation
  BUILDERS_GUIDE.md   AI-guided learning roadmap with math optimizations

Learning Path

See docs/BUILDERS_GUIDE.md for a guided roadmap that teaches full-stack development through building new features for this app. Each feature introduces a mathematical optimization from the Asymmetrica research project.

License

MIT