task/1.8
Raw Download raw file

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Start for New Sessions

Before starting any work, read these files in order:

0. **RFD 002** - Our workflow process for task-driven development - `docs/rfd/002/README.md`
0. **Project Plan** - Current progress and next task to work on - `docs/project_plan.md` 
0. **RFD 004** - Overall architecture and design decisions - `docs/rfd/004/README.md`
0. **RFD Table of Contents** - Additional lessons learned and implementation decisions - `docs/rfd/README.md` 
0. Appropriate RFDs based on topic and task

Project Overview

This is a Go web application for “buylater.email” - an email-based delayed gratification shopping service. The application is designed to help users delay purchases by scheduling reminder emails for future dates, promoting intentional consumption over impulse buying.

Core Business Concept (from RFD 003)

  • Users submit product URLs with their email address
  • System schedules reminder emails (3 days, 2 weeks, or custom dates)
  • Final emails include affiliate-tagged purchase links for monetization
  • Privacy-first approach with minimal data retention
  • “Buy less, buy better” philosophy - restoring friction to the buying process
  • Monetized purely via affiliate commissions (no ads, upsells, or data sales)
  • Goals: No passwords, no app, no fluff - extremely lightweight and fast
  • Target: Profitability at 1,000 users/month with minimal infrastructure

Workflow Reminders

IMPORTANT: Always follow RFD 002 workflow process:

  1. Create task branch before starting work (git checkout -b task/X.Y)
  2. Make incremental commits during development
  3. Follow proper commit message format from RFD 002 (Task X.Y: description, bullets, See: reference)
  4. Request human verification before marking tasks complete
  5. Update project_plan.md status when tasks are completed

Development Commands

make build     # Build application binary (with vendor unpack)
make test      # Run tests (with vendor unpack)
make fmt       # Format code
make lint      # Lint code (vet + format check)
make update    # Update dependencies and vendor pack

Direct Go Commands

go run cmd/web/*.go   # Run application (port 4000)
go build ./cmd/web    # Build application
go test ./...         # Run tests
go fmt ./...          # Format code
go vet ./...          # Vet code
go mod tidy           # Clean up dependencies
go mod download       # Download dependencies

Architecture

Current Structure

buylater/
├── cmd/
│   └── web/
│       ├── main.go      - Application entry point
│       └── handlers.go  - HTTP handler functions
├── internal/            - Internal packages (future)
├── tools/
│   └── vendor/         - Vendor dependency management tools
│       ├── pack.go     - Create vendor.tar.gz from vendor/ dir
│       ├── unpack.go   - Extract vendor.tar.gz to vendor/ dir
│       └── vendor.tar.gz - Compressed vendor dependencies
├── ui/
│   ├── html/           - HTML templates
│   │   └── pages/      - Page templates
│   └── static/         - Static assets (future)
├── docs/               - Documentation and RFDs
├── Makefile            - Build automation (5 targets)
└── go.mod

Key Concepts

  • The application uses Go’s standard net/http package for web functionality
  • Follows proper Go project layout with cmd/web structure
  • Uses html/template package for rendering HTML templates
  • Handlers separated from main application logic
  • Template files organized in ui/html directory structure
  • Vendor dependencies managed via compressed tar.gz to keep repo clean
  • Makefile provides 5 essential build targets with vendor integration

Documentation

  • docs/lets-go/ - “Let’s Go” tutorial materials for learning Go web development
  • docs/rfd/ - Request for Discussion documents following the RFD process (RFD 001)

Request for Discussion (RFD) Process

This project follows a formal RFD process for documenting and discussing technical and organizational decisions:

RFD States

  • prediscussion - Work in progress, not ready for discussion
  • ideation - Topic description only
  • discussion - Under active discussion in Pull Request
  • published - Discussion converged, merged to main
  • committed - Fully implemented
  • abandoned - Non-viable or should be ignored

Current RFDs

  • RFD 001: Establishes the RFD process itself (state: discussion)
  • RFD 002: Defines the buylater.email service concept (state: pre-discussion)
  • RFD 003: buylater.email service - detailed business concept, user flow, and monetization strategy (state: pre-discussion)
  • RFD 004: Choosing Golang as the primary language - justifies Go for simplicity, concurrency, and deployment benefits (state: pre-discussion)

Development Notes

  • Module name: github.com/bryfry/buylater
  • Go version: 1.24.2
  • No external dependencies currently defined in go.mod
  • The codebase is minimal and appears to be in the initial setup phase
  • Project follows privacy-first principles and aims for minimal infrastructure

Language Choice Rationale (from RFD 004)

Go was chosen as the primary language because it provides:

  • Simplicity: Low barrier to entry for new contributors with clean, readable syntax
  • Concurrency: Goroutines and channels for handling multiple scheduled emails efficiently
  • Deployment: Single static binary with zero dependencies - ideal for cheap VPS hosting
  • Performance: Near C-level performance with minimal optimization effort
  • Tooling: Built-in formatting, testing, vetting, and documentation tools
  • Standard Library: Robust native libraries for HTTP, crypto, templating, and time handling
  • Project Fit: Perfect for stateless HTTP endpoints, scheduled email delivery, and transparent code

Core Technical Requirements (from RFD 003)

  • User Flow: Submit URL → Email confirmation → Scheduled reminder with affiliate links
  • Email Deliverability: Use reputable providers (Postmark, SES) with warm sender domain
  • Security: Double opt-in, rate limiting, tokenized URLs for one-click interactions
  • Infrastructure: Minimal setup - single process handling HTTP and scheduled jobs
  • Monetization: Affiliate program integration (primarily Amazon Associates)
  • Non-Goals: No user tracking, no upsells, no data sales - privacy-first approach