task_id: “1.7” title: “Project Structure and Organization” status: “pending” priority: “high” estimated_effort: “medium” created: “2025-07-22” assigned_to: “pair” related_rfds: “RFD 004”

Task 1.7: Project Structure and Organization

Summary

Restructure the buylater.email project following Go best practices and the Let’s Go book structure to improve maintainability and scalability.

Motivation

Following Let’s Go Chapter 2.7, we need to organize our growing codebase into a proper structure that separates concerns and follows Go conventions. Moving from a single main.go file to a well-organized directory structure will make the project more maintainable as we add features.

Acceptance Criteria

• Create proper directory structure with cmd/web, internal, ui/html, ui/static
• Move main.go to cmd/web/main.go
• Create cmd/web/handlers.go for HTTP handler functions
• Separate concerns between application entry point and business logic
• Maintain all existing functionality after restructuring
• Update module imports and package structure
• Ensure application still runs correctly on port 4000

Technical Requirements

Directory Structure

buylater/
├── cmd/
│   └── web/
│       ├── main.go
│       └── handlers.go
├── internal/
├── ui/
│   ├── html/
│   └── static/
├── go.mod
└── go.sum

Implementation Details

• Move current main.go content to cmd/web/main.go
• Extract handler functions to cmd/web/handlers.go
• Create package structure for buylater-specific functionality
• Update import paths to use github.com/bryfry/buylater/cmd/web
• Ensure proper separation between main() and handler logic

Dependencies

• Task 1.6 completed (custom response headers)

Testing Strategy

Unit Tests

• Verify all handlers work after restructuring
• Test package imports resolve correctly

Integration Tests

• All routes still accessible after structure change
• Server starts correctly from new location

Manual Testing

• Run go run cmd/web/*.go successfully starts server on port 4000
• All existing routes (/, /buygone/view, /buygone/create) work correctly
• POST /submit still returns 201 Created with proper headers
• Verify go build ./cmd/web creates executable

Definition of Done

• All acceptance criteria met
• All specified tests pass
• Code follows project conventions (go fmt, go vet)
• No new console errors or warnings
• Application runs with new structure
• Human verification completed successfully
• Git commit created with proper message format

Implementation Notes

Approach

Gradually restructure the project by creating the new directory layout and moving code while maintaining functionality. Focus on clean separation of concerns.

Key Files to Create/Modify

• cmd/web/main.go - Application entry point
• cmd/web/handlers.go - HTTP handler functions
• internal/ - Future internal packages
• ui/html/ - Future HTML templates
• ui/static/ - Future static assets

Potential Risks

• Import path changes could break builds
• Package structure must be compatible with Go module system
• Handler function signatures must remain compatible

Success Metrics

Cleanly organized project structure that follows Go conventions and maintains all existing functionality while providing foundation for future growth.

Related Tasks

• Blocks: Future templating, static file serving, and advanced features
• Blocked by: Task 1.6 (needs completed foundation)
• Related: Clean architecture and maintainable code organization

Implementation Log

Implementation details will be recorded here during development.

Final Verification

Human Tester: [Name]
Date Completed: [YYYY-MM-DD]
Verification Result: [Pass/Fail]
Notes: [Any issues found or additional observations]