tudoolist

A minimal, beautiful task tracker built with Go and HTMX.

Features

• Task Management - Create, organize, and track your daily tasks
• Progress Tracking - Add updates and checklist items to monitor progress
• Pin Important Tasks - Keep critical tasks visible at the top
• Work/Personal Tags - Categorize tasks for better organization
• Weekly Stats - Track your productivity with completion metrics
• Persistent Sessions - Stay logged in for 30 days with Remember Me

Tech Stack

• Backend: Go 1.24 with chi router
• Frontend: HTMX + Tailwind CSS v4
• Database: SQLite with WAL mode
• Sessions: Database-backed (SCS)
• UI Style: Claymorphism with retro color palette
• Testing: Comprehensive unit tests (~80% coverage)

Quick Start

Run Locally

# Clone the repository
git clone https://github.com/tuntran/tudoolist.git
cd tudoolist

# Run with Go
go run ./cmd/server

# Or with hot reload (requires Air)
make dev

Visit http://localhost:8080 and create an account to get started.

Run with Docker

# Using Docker Compose
docker-compose up -d

# Access the app
open http://localhost:8080

Data persists in a Docker volume at /app/data.

Development

Prerequisites

• Go 1.24+
• SQLite (embedded)
• Air (optional, for hot reload)
• Tailwind CLI (optional, for CSS changes)

Project Structure

tudoolist/
├── cmd/server/          # Application entry point
├── internal/            # Private packages
│   ├── auth/           # Authentication
│   ├── task/           # Task management
│   ├── database/       # Database layer
│   └── testutil/       # Test utilities
├── web/
│   ├── templates/      # HTML templates
│   └── static/         # CSS and JS
├── migrations/         # SQL migrations
└── docs/               # Documentation

Running Tests

# Run all tests
go test ./...

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

# Run specific package tests
go test ./internal/auth -v

Building

# Build binary
go build -o tudoolist ./cmd/server

# Build Docker image
docker build -t tudoolist:latest .

Documentation

• Project Overview & PDR - Product requirements and features
• System Architecture - Technical architecture and design
• Code Standards - Coding conventions and best practices
• Codebase Summary - Code organization and components
• Project Roadmap - Future plans and versioning

Deployment

Environment Variables

• ADDR - Server address (default: :8080)
• COOKIE_SECURE - Enable secure cookies for HTTPS (default: false)

Docker Deployment

# docker-compose.yaml
services:
  tudoolist:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - COOKIE_SECURE=true

Reverse Proxy

For production deployment behind Nginx/Caddy:

location / {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Set COOKIE_SECURE=true when serving over HTTPS.

Architecture Highlights

• Clean Architecture - Handler → Service → Repository layers
• Server-Side Rendering - HTMX for dynamic updates without SPA complexity
• Repository Pattern - Clear separation of data access
• Dependency Injection - Testable, maintainable code
• Context Propagation - Request-scoped data flow
• WAL Mode - Concurrent reads with SQLite

Testing Strategy

• Unit Tests - Service and repository logic (80% coverage)
• Test Utilities - In-memory database for fast tests
• Integration Tests - Planned for handlers (v1.1)
• E2E Tests - Planned with Playwright (v1.1)

Contributing

Contributions welcome! Please read the Code Standards before submitting PRs.

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure tests pass: go test ./...
5. Submit a pull request

License

MIT License - See LICENSE file for details.

Acknowledgments

• Built with chi router
• Sessions with SCS
• Frontend powered by HTMX
• Styled with Tailwind CSS
• Icons from Lucide