# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Architecture Overview

GoCheck is a real-time collaborative checklist application with an **SSE-first architecture**:
- **Backend**: Go server with SQLite (one DB per checklist) - located in `backend/` directory
- **Frontend**: React TypeScript SPA with Radix UI and Tailwind CSS - located in `frontend/` directory
- **Real-time**: All data flows through Server-Sent Events - no polling or API calls for data retrieval
- **Embedded**: Frontend is built and embedded into the Go binary for single-file deployment

## Common Development Commands

### Backend (Go)
```bash
# Build the complete application (frontend + backend)
./build.sh

# Run the server
./gocheck

# Development with hot reload (requires Air)
cd backend && air

# Full dev environment (backend + frontend hot reload)
./dev.sh
```

### Frontend (React/TypeScript)  
```bash
# Install dependencies
cd frontend && npm install

# Development server (proxies to backend on :8080)
cd frontend && npm run dev

# Build for production
cd frontend && npm run build

# Lint code
cd frontend && npm run lint

# Type checking
cd frontend && npm run build  # TypeScript checking is part of build
```

### Container Operations
```bash
# Build and push multi-arch container
./build-and-push.sh

# Docker development environment
./dev-docker.sh
```

## Key Architecture Patterns

### SSE-First Data Flow
The application **never** uses REST endpoints for data retrieval. All checklist data flows through SSE:
1. Client connects to `/api/checklists/{uuid}/sse`
2. Server sends complete state on connection
3. All updates broadcast via SSE events
4. Frontend maintains state purely from SSE messages

### Database Design
- Each checklist has its own SQLite database in `backend/data/{uuid}.db`
- Schema includes: `checklist_info`, `items`, and `dependencies` tables
- Item dependencies and date constraints are core features

### API Endpoints
All endpoints return consistent JSON with `success` and `message` fields:
- `POST /api/checklists` - Create checklist
- `POST /api/checklists/{uuid}/items` - Add item
- `PATCH /api/checklists/{uuid}/items/{id}` - Update item
- `DELETE /api/checklists/{uuid}/items/{id}` - Delete item
- `POST /api/checklists/{uuid}/items/{id}/lock` - Lock item
- `GET /api/checklists/{uuid}/sse` - SSE stream (primary data source)

### Frontend Structure
- `frontend/src/pages/`: Home and Checklist pages
- `frontend/src/components/`: Reusable components (ChecklistItem, DependencyManager, etc.)
- `frontend/src/hooks/`: Custom hooks including `useSSE` for real-time updates
- Uses React Router for navigation
- Uses Radix UI for accessible, modern UI components
- Local storage for saving checklist UUIDs

### Development Notes
- No test suite currently exists
- ESLint configured with no-semicolon style
- Frontend uses Vite for fast development
- Backend embeds frontend dist for production deployment
- Container builds support multi-arch (amd64/arm64)