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)

# 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)

# 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

# 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:

Client connects to /api/checklists/{uuid}/sse
Server sends complete state on connection
All updates broadcast via SSE events
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)

3 KiB Raw Blame History