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

   git clone <repository-url>
   cd gocheck
   

2. Development mode (with hot reload):

   ./dev.sh
   

   This starts both backend (port 8080) and frontend (port 5173) with hot reloading.

3. Production build:

   ./build.sh
   ./gocheck
   

   The server will start on http://localhost:8080

Manual Development Setup

Backend

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

Frontend

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:

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

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

{
  "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]