Skip to content

Development Guide

Jump to bottom
Gary Norman edited this page Oct 7, 2025 · 1 revision

Development Guide

Code Style

Go Code

  • Follow Effective Go
  • Use gofmt for formatting
  • Run go vet before committing
  • Write tests for new features

JavaScript

  • Use vanilla JavaScript (no frameworks)
  • Follow consistent naming conventions
  • Comment complex logic
  • Use ES6+ features appropriately

CSS

  • Use CSS variables for theming
  • Follow BEM naming convention where appropriate
  • Keep selectors specific but not overly nested
  • Use Flexbox and Grid for layouts

Git Workflow

Commit Messages

Follow conventional commits format:

type(scope): subject

body (optional)

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • style: Code style changes
  • refactor: Code refactoring
  • test: Testing
  • chore: Maintenance

Example:

feat(auth): add password reset functionality

Implements password reset via email with secure tokens.
Includes rate limiting to prevent abuse.

Branching

  • main - Production-ready code
  • feature/* - New features
  • fix/* - Bug fixes
  • docs/* - Documentation

Pull Requests

  1. Create a feature branch
  2. Make your changes
  3. Write/update tests
  4. Update documentation
  5. Submit PR with description
  6. Address review comments
  7. Squash and merge

Testing

Unit Tests

go test ./...

Integration Tests

go test -tags=integration ./...

Manual Testing

Use the interactive menu:

make menu

Building

Local Development

make build
make run

Docker

make configure
make build-image
make run-container

Debugging

Using pprof

The application runs a pprof server on localhost:6060:

# CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile

# Heap profile
go tool pprof http://localhost:6060/debug/pprof/heap

# Goroutines
go tool pprof http://localhost:6060/debug/pprof/goroutine

Logging

Logs use the Catppuccin Mocha color scheme for readability:

  • Pink: Errors and important info
  • Green: Success messages
  • Blue: General info
  • Yellow: Warnings

Common Tasks

Adding a New Handler

  1. Create handler struct in internal/http/handlers/
  2. Implement handler methods
  3. Add to registry in internal/http/routes/registry.go
  4. Define routes in internal/http/routes/routes.go

Adding a Database Table

  1. Create migration in migrations/
  2. Define model in internal/models/
  3. Create SQLite implementation in internal/sqlite/
  4. Run migration: bin/codex migrate

Adding a Template

  1. Create template in assets/templates/
  2. Register in internal/view/render.go
  3. Use in handler

Performance Tips

  • Use database indexes for common queries
  • Cache template parsing
  • Minimize middleware overhead
  • Use connection pooling
  • Profile with pprof regularly

Security Considerations

  • Always validate user input
  • Use parameterized SQL queries
  • Hash passwords with bcrypt
  • Implement rate limiting
  • Sanitize HTML output
  • Use HTTPS in production
  • Set secure cookie flags

Clone this wiki locally