93 lines
No EOL
3 KiB
Markdown
93 lines
No EOL
3 KiB
Markdown
# 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) |