Event Planner

A lightweight, self-contained web application for comprehensive family event management. Built with Go, SQLite, and HTMX for simplicity and ease of deployment.

Project Goals

Event Planner is designed to simplify family event organization by handling three main phases:

1. Pre-event Planning - Collaborative shopping lists with real-time updates
2. Post-event Settlement - Automatic expense tracking and fair cost distribution
3. Memory Collection - Photo and video uploads with gallery viewing

Design Principles

• Simplicity over complexity - Minimal dependencies, straightforward architecture
• Self-contained - Single binary deployment with embedded SQLite database
• No heavy frameworks - Server-side HTML rendering with HTMX for dynamic interactions
• CLI parity - All major actions available via command-line interface
• Family-friendly - Designed for occasional use in trusted environments

Current Status & Roadmap

✅ Completed (Phases 1-5)

• Phase 1: Foundation & project structure
• Phase 2: Event management (create, list, view, delete)
• Phase 3: Participant authentication with invite tokens
• Phase 4: Collaborative shopping list with HTMX polling
• Phase 5: Expense tracking and settlement calculation

🚧 Planned Features

• Phase 6: Media gallery with photo/video uploads and thumbnails
• Phase 7: Anonymous access via QR codes for guest uploads
• Phase 8: Polish, backup functionality, and production hardening

🔧 Recent Improvements

• Migrated to sqlx for better struct scanning and query ergonomics
• Integrated squirrel for type-safe SQL query building
• Refactored database schema to use lowercase column names matching Go conventions
• Comprehensive test coverage with unit and integration tests

How to Use

Starting the Server

# Run the server (default port 8080)
./bin/server serve

# Specify custom port
./bin/server serve --port 3000

# Use custom database file
./bin/server serve --db-path ./myevents.db

The server will be available at http://localhost:8080

Using the Web Interface

1. Create an Event

   • Navigate to the home page
   • Click "Create New Event"
   • Fill in event details (name, date, location, description)

2. Add Participants

   • Use the CLI to add participants and generate invite tokens
   • Share invite links with participants via messaging apps

3. Manage Shopping List

   • Navigate to the event's shopping list
   • Add items, assign to participants, mark as purchased
   • List updates automatically every 5 seconds

4. Track Expenses

   • Add expenses with amount and description
   • View settlement report to see who owes whom
   • Equal split calculation across all participants

Using the CLI

# Create a new event
./bin/server event create "Birthday Party" --date "2024-12-25" --location "Home"

# List all events
./bin/server event list

# Add a participant to an event
./bin/server event participant add 1 "Alice" --email "alice@example.com"

# List participants for an event
./bin/server event participant list 1

# Delete an event
./bin/server event delete 1

Development Setup

Required Dependencies

• Go 1.24.3+ - Programming language
• golangci-lint - Linting tool (optional but recommended)
• Make - Build automation

Installing Dependencies

# Install Go (if not already installed)
# Visit: https://golang.org/doc/install

# Install golangci-lint (optional)
# Visit: https://golangci-lint.run/usage/install/

# Install project dependencies
go mod download

Project Structure

eventplanner/
├── cmd/server/          # Application entry point
├── internal/
│   ├── database/        # Database layer (sqlx + squirrel)
│   ├── domain/          # Domain models and business logic
│   └── web/            # HTTP handlers and templates
├── ARCHITECTURE.md      # Detailed technical specification
├── IMPLEMENTATION.md    # Phase-by-phase implementation plan
└── Makefile            # Build and development tasks

Development Workflow

# Run tests
make test

# Run linter
make lint

# Build the binary
make build

# Run all checks (test + lint + build)
make all

# Run the server in development mode
make dev

# Clean build artifacts
make clean

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/database

Code Style

• Follow standard Go conventions
• Use gofmt for formatting (automatically applied by make commands)
• Pass golangci-lint checks before committing
• Write tests for all new features

Database Schema

The application uses SQLite with the following conventions:

• Lowercase column names without underscores (e.g., eventid, guesttoken)
• Auto-mapping to Go struct fields via sqlx
• Foreign key constraints with CASCADE and SET NULL policies

Installation

From Source

# Clone the repository
git clone https://github.com/mgdelacroix/eventplanner.git
cd eventplanner

# Build the binary
make build

# The binary will be in ./bin/server
./bin/server --help

Quick Start

# Build and run
make run

# Or build first, then run
make build
./bin/server serve

Production Deployment

The application is designed for simple deployment:

1. Build the binary: make build
2. Copy ./bin/server to your server
3. Run the server: ./server serve --port 8080
4. Database is created automatically at eventplanner.db
5. Backup by copying the SQLite database file

Environment Variables

# Database file path
export DB_PATH="/path/to/database.db"

# Server port
export PORT=8080

# Run server
./bin/server serve

System Requirements

• CPU: Any modern processor (minimal resource usage)
• RAM: ~10-20 MB
• Disk: Depends on uploaded media (database alone is very small)
• OS: Linux, macOS, or Windows (Go cross-platform compatibility)

Technology Stack

Backend

• Go 1.24.3 - Programming language
• SQLite (modernc.org/sqlite) - Embedded database
• sqlx - SQL extensions for better struct scanning
• squirrel - SQL query builder
• kong - CLI argument parser

Frontend

• HTML Templates - Server-side rendering
• HTMX - Dynamic interactions without heavy JavaScript
• Vanilla CSS - Simple styling

Testing

• Go testing - Standard library testing
• httptest - HTTP handler testing
• In-memory SQLite - Fast test database

Continuous Integration

The project uses Forgejo Actions for automated testing and quality checks. On every push and pull request, the CI pipeline runs:

Parallel Jobs

1. Code Style Check (lint)

   • Runs golangci-lint to check code quality
   • Verifies code formatting with gofmt

2. Run Tests (test)

   • Executes all tests with race detection
   • Generates coverage reports
   • Warns if coverage drops below 50%

Sequential Job

3. Build Binary (build)
   • Runs only after lint and test pass
   • Builds the application binary
   • Verifies the binary runs correctly
   • Uploads binary as artifact (7-day retention)

All checks must pass before code can be merged.

Contributing

This project follows a phased implementation plan (see IMPLEMENTATION.md). Each phase includes:

• Database schema updates
• Repository layer implementation
• Web handlers and templates
• Comprehensive tests
• Linting compliance

Please ensure all tests pass and linting succeeds before submitting changes. The CI pipeline will automatically verify:

• ✅ Code passes linting
• ✅ All tests pass
• ✅ Code is properly formatted
• ✅ Binary builds successfully

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

Miguel de la Cruz - @mgdelacroix