cheekylist/README.md

# GoCheck - Collaborative Checklist Application

A real-time collaborative checklist application built with Go and React, featuring Server-Sent Events (SSE) for live updates and SQLite for data persistence.

## Features

- Create and manage checklists
- Add, update, and delete checklist items
- Real-time collaboration with Server-Sent Events
- Item locking mechanism to prevent conflicts
- **Item dependencies**: Define prerequisites for completing items
- **Date constraints**: Set "not before" and "not after" times for item completion
- Modern web frontend with React, TypeScript, and Radix UI
- Real-time updates across multiple browser tabs/windows
- SSE-first architecture: All data flows through Server-Sent Events
- Export/Import checklists as JSON

## Architecture

### Project Structure

```
gocheck/
├── backend/           # Go server code
│   ├── main.go
│   ├── go.mod
│   ├── database/     # SQLite database handling
│   ├── handlers/     # HTTP and SSE handlers
│   ├── models/       # Data models
│   ├── sse/         # Server-Sent Events implementation
│   └── static/      # Static file serving
├── frontend/         # React TypeScript application
│   ├── src/
│   ├── package.json
│   └── vite.config.ts
├── build.sh         # Build script for production
├── dev.sh          # Development script with hot reload
└── Containerfile   # Multi-stage container build
```

### SSE-First Design

This application follows an **SSE-first architecture** where all checklist data flows through Server-Sent Events:

- **No polling**: The frontend never polls for data updates
- **Real-time state management**: The frontend maintains state purely through SSE events
- **Immediate updates**: Changes appear instantly across all connected clients

## Prerequisites

- Go 1.24 or later
- Node.js 22+ and npm
- SQLite3 (included with Go)

## Setup and Development

### Quick Start

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd gocheck
   ```

2. **Development mode** (with hot reload):
   ```bash
   ./dev.sh
   ```
   This starts both backend (port 8080) and frontend (port 5173) with hot reloading.

3. **Production build**:
   ```bash
   ./build.sh
   ./gocheck
   ```
   The server will start on `http://localhost:8080`

### Manual Development Setup

#### Backend
```bash
cd backend
go mod download
air  # For hot reload (requires Air to be installed)
# or
go run main.go
```

#### Frontend
```bash
cd frontend
npm install
npm run dev  # Development server on port 5173
npm run build  # Production build
npm run lint  # Check code quality
```

## Deployment

### Binary Deployment

The application builds as a single binary with embedded static files:

```bash
# Build for current platform
./build.sh

# Cross-platform builds
cd backend
GOOS=linux GOARCH=amd64 go build -o gocheck-linux
GOOS=windows GOARCH=amd64 go build -o gocheck.exe
GOOS=darwin GOARCH=amd64 go build -o gocheck-macos
```

### Container Deployment

Build and run with Podman or Docker:

```bash
# Using the build script
./build-and-push.sh

# Manual build
podman build -t gocheck -f Containerfile .
podman run -d --name gocheck -p 8080:8080 -v gocheck-data:/app/backend/data gocheck

# With custom port
podman run -d --name gocheck -p 3000:8080 -e PORT=8080 -v gocheck-data:/app/backend/data gocheck
```

## API Endpoints

All endpoints return consistent JSON responses:

```json
{
  "success": true,
  "message": "Operation completed",
  "data": {}
}
```

### Endpoints

- `POST /api/checklists` - Create a new checklist
- `PATCH /api/checklists/{uuid}/name` - Update checklist name
- `POST /api/checklists/{uuid}/items` - Add an item
- `PATCH /api/checklists/{uuid}/items/{id}` - Update an item
- `DELETE /api/checklists/{uuid}/items/{id}` - Delete an item
- `POST /api/checklists/{uuid}/items/{id}/lock` - Lock an item for editing
- `GET /api/checklists/{uuid}/sse` - SSE stream for real-time updates

## Frontend Features

Built with modern web technologies:
- **React 18** with TypeScript
- **Radix UI** for accessible, customizable components
- **Tailwind CSS** for styling
- **Vite** for fast development and building
- **React Router** for client-side routing

### Key Features

- **Home Page**: Create new checklists and manage saved ones
- **Checklist Page**: Real-time collaborative editing
- **Local Storage**: Automatically saves checklist references
- **Export/Import**: Save and load checklists as JSON files
- **Mobile Friendly**: Responsive design with native date/time inputs

## Database

SQLite databases are stored in `backend/data/` with one database per checklist:

- `checklist_info` - Checklist metadata
- `items` - Checklist items with dependencies and date constraints
- `dependencies` - Item dependency relationships

## Item Dependencies

Items can depend on other items being completed first:

1. Click the link icon (🔗) on any item
2. Select which items must be completed first
3. Items with unmet dependencies cannot be checked off
4. Visual indicators show dependency status

## Date Constraints

Set time windows for when items can be completed:

1. Click the clock icon (🕐) on any item
2. Set "not before" and/or "not after" times
3. Quick select buttons for common timeframes
4. Items cannot be completed outside their time window

## Development Tools

### Scripts

- `./dev.sh` - Start development environment with hot reload
- `./build.sh` - Build production binary
- `./build-and-push.sh` - Build and push container images

### Environment Variables

- `PORT` - Server port (default: 8080)

## Contributing

1. Follow the existing code style
2. Use ESLint for frontend code (no semicolons)
3. Test changes in both development and production modes
4. Ensure cross-platform compatibility

## License

[Add your license here]