# CLAUDE.md

## Commands

```bash
./script/dev              # Start backend + frontend
./script/test             # Run E2E tests
```

### Backend

```bash
cd server
clj -M:dev                # Start REPL with dev tools
clj -M:run                # Start server (production mode)
clj -M:test               # Run unit tests
```

**REPL commands:**
```clojure
(go)                      ; Start server + file watcher
(reset)                   ; Reload code
(stop)                    ; Stop server
```

### Frontend

```bash
cd client
npm install
npm run dev               # Dev server
npm run build             # Production build
npm run check             # TypeScript check
```

### E2E Tests

```bash
cd e2e
npm test
npm run test:headed       # Visible browser
npm run test:ui           # Interactive explorer
```

## Architecture

### Backend

```
server/src/spiceflow/
├── core.clj              # Entry point
├── config.clj            # Settings from config.edn
├── db/
│   ├── protocol.clj      # DataStore interface
│   ├── sqlite.clj        # SQLite implementation
│   └── memory.clj        # In-memory (tests)
├── adapters/
│   ├── protocol.clj      # AgentAdapter interface
│   ├── claude.clj        # Claude Code CLI
│   ├── opencode.clj      # OpenCode CLI
│   └── tmux.clj          # Terminal multiplexer
├── api/
│   ├── routes.clj        # HTTP endpoints
│   └── websocket.clj     # Real-time streaming
└── session/
    └── manager.clj       # Session lifecycle
```

### Frontend

```
client/src/
├── routes/               # SvelteKit file-based routing
│   ├── +layout.svelte
│   ├── +page.svelte      # Home (session list)
│   └── session/[id]/+page.svelte
├── lib/
│   ├── api.ts            # HTTP + WebSocket client
│   ├── stores/sessions.ts
│   └── components/
└── app.css               # Tailwind
```

### Protocols

Database and CLI adapters use protocols for swappability:

```clojure
(defprotocol DataStore
  (get-sessions [this])
  (save-message [this msg]))

(defprotocol AgentAdapter
  (spawn-session [this session])
  (send-message [this session msg]))
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Health check |
| `/api/sessions` | GET | List sessions |
| `/api/sessions` | POST | Create session |
| `/api/sessions/:id` | GET | Get session with messages |
| `/api/sessions/:id` | PATCH | Update session |
| `/api/sessions/:id` | DELETE | Delete session |
| `/api/sessions/:id/send` | POST | Send message |
| `/api/sessions/:id/permission` | POST | Handle permission |
| `/api/sessions/:id/terminal` | GET | Get tmux content |
| `/api/sessions/:id/terminal/input` | POST | Send tmux input |
| `/api/ws` | WebSocket | Event streaming |

## Configuration

Environment variables or `server/resources/config.edn`:

| Variable | Default | Description |
|----------|---------|-------------|
| `SPICEFLOW_PORT` | 3000 | Server port |
| `SPICEFLOW_HOST` | 0.0.0.0 | Server host |
| `SPICEFLOW_DB` | spiceflow.db | SQLite path |
| `CLAUDE_SESSIONS_DIR` | ~/.claude/projects | Claude sessions |
| `OPENCODE_CMD` | opencode | OpenCode binary |

## Testing Changes

Always test changes before considering them complete. Choose the appropriate testing method:

### 1. E2E Tests (Playwright)
For UI changes, user flows, and integration between frontend/backend:
```bash
cd e2e && npm test                    # Run all E2E tests
cd e2e && npm run test:headed         # Visible browser for debugging
cd e2e && npm test -- -g "test name"  # Run specific test
```

### 2. Unit Tests (Clojure)
For backend logic, pure functions, and isolated components:
```bash
cd server && clj -M:test              # Run all unit tests
```

### 3. REPL Testing
For quick one-off validation of Clojure code during development:
```clojure
;; In REPL (clj -M:dev, then (go))
(require '[spiceflow.some-ns :as ns])
(ns/some-function arg1 arg2)          ; Test function directly
```

### 4. Manual API Testing
For testing HTTP endpoints directly:
```bash
# Health check
curl http://localhost:3000/api/health

# List sessions
curl http://localhost:3000/api/sessions

# Create session
curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"provider": "claude"}'

# Get session
curl http://localhost:3000/api/sessions/:id
```

### When to Use Each
| Change Type | Recommended Testing |
|-------------|---------------------|
| UI component | E2E tests |
| API endpoint | Manual API + unit tests |
| Business logic | Unit tests + REPL |
| User flow | E2E tests |
| Bug fix | Add regression test + manual verify |

## Subdirectory CLAUDE.md Files

Each directory has specific details:
- `server/` - REPL workflow, Mount lifecycle
- `server/src/spiceflow/db/` - Schema, queries
- `server/src/spiceflow/adapters/` - Adding adapters
- `server/src/spiceflow/api/` - HTTP handlers, WebSocket
- `server/src/spiceflow/session/` - Session state
- `client/` - SvelteKit, PWA
- `client/src/lib/` - API client, stores
- `client/src/routes/` - Pages, routing
- `e2e/` - E2E tests