go-garth/.clinerules/localrules.md

• when developing go code use the standard go tools
• always execute commands from the root of the project
• in ACT mode if you hit 5 errors in a row return to plan mode
• Both backend and frontend applications must read from the root .env file
• always prefer small targeted changds over big changes
• use the python implementation a core reference before making changes. That version works and will provide insights for solving issues.

Testing Requirements

• MANDATORY: Run all tests in containerized environments
• Follow testing framework conventions (pytest for Python, Jest for React)
• Include unit, integration, and end-to-end tests
• Test data should be minimal and focused
• Separate test types into different directories

TESTING

• when asked to resolve errors:
  • iterate until all builds complete with no errors
  • the commmand should be run from the root of the project: go build ./...

Go Formatting

When work is done the following shouldbe run

• go mod tidy
• go fmt ./...
• go vet ./...
• go test ./...

Rule 13: Database Configuration

• Use environment variables for database configuration
• Implement proper connection pooling
• Follow database naming conventions
• Mount database data as Docker volumes for persistence

Project Structure:

• MANDATORY: All new code must follow the standardized project structure
• MANDATORY: Core backend logic only in /src/ directory
• MANDATORY: Frontend code only in /frontend/ directory
• MANDATORY: All Docker files in /docker/ directory

Package Management:

• MANDATORY: Use UV for Python package management
• MANDATORY: Use pnpm for React package management
• MANDATORY: Dependencies declared in appropriate configuration files

Code Quality:

• MANDATORY: Run linting before building
• MANDATORY: Resolve all errors before deployment
• MANDATORY: Follow language-specific coding standards

Project Organization:

• FORBIDDEN: Data files committed to git
• FORBIDDEN: Configuration secrets in code
• FORBIDDEN: Environment variables in subdirectories

Pre-Deployment Checklist:

1. All tests passing
2. Linting and type checking completed
3. Environment variables properly configured
4. Database migrations applied
5. Security scan completed

Do at every iteration

• check the rules
• when you finish a task or sub-task update the todo list

GoLang Rules

Interface and Mock Management Rules

• Always implement interfaces with concrete types - Never use anonymous structs with function fields to satisfy interfaces
• Create shared mock implementations - Don't duplicate mock types across test files; use a central test_helpers.go file
• One mock per interface - Each interface should have exactly one shared mock implementation for consistency
• Use factory functions for mocks - Provide NewMockXXX() functions to create mock instances with sensible defaults
• Make mocks configurable when needed - Use function fields or configuration structs for tests requiring custom behavior

Test Organization Rules

• Centralize test utilities - Keep all shared test helpers, mocks, and utilities in test_helpers.go or similar
• Follow consistent patterns - Use the same approach for creating clients, sessions, and mocks across all test files
• Don't pass nil for required interfaces - Always provide a valid mock implementation unless specifically testing nil handling
• Use descriptive mock names - Name mocks clearly (e.g., MockAuthenticator, MockHTTPClient) to indicate their purpose

Code Change Management Rules

• Update all dependent code when changing interfaces - If you modify an interface, check and update ALL implementations and tests
• Run full test suite after interface changes - Interface changes can break code in unexpected places
• Search codebase for interface usage - Use grep or IDE search to find all references to changed interfaces
• Update mocks when adding interface methods - New interface methods must be implemented in all mocks

Testing Best Practices Rules

• Test with realistic mock data - Don't use empty strings or zero values unless specifically testing edge cases
• Set proper expiration times - Mock sessions should have future expiration times unless testing expiration
• Verify mock behavior is called - Add call tracking to mocks when behavior verification is important
• Use table-driven tests for multiple scenarios - Test different mock behaviors using test case structs
• Mock external dependencies only - Don't mock your own business logic; mock external services, APIs, and I/O

Documentation and Review Rules

• Document shared test utilities - Add comments explaining when and how to use shared mocks
• Include interface changes in code reviews - Flag interface modifications for extra review attention
• Update README/docs when adding test patterns - Document new testing patterns for other developers
• Add examples for complex mock usage - Show how to use configurable mocks in comments or examples

Error Prevention Rules

• Compile-test interface changes immediately - Run go build after any interface modification
• Write interface compliance tests - Add var _ InterfaceName = (*MockType)(nil) to verify mock implements interface
• Set up pre-commit hooks - Use tools like golangci-lint to catch interface issues before commit
• Review test failures carefully - Interface-related test failures often indicate broader architectural issues

Refactoring Safety Rules

• Create shared mocks before removing duplicates - Implement the centralized solution before removing old code
• Update one test file at a time - Incremental changes make it easier to identify and fix issues
• Keep backup of working tests - Commit working tests before major refactoring
• Test each change independently - Verify each file works after updating it
• Use version control effectively - Make small, focused commits that are easy to review and revert

Learning Points

• Interface Implementation: Go interfaces must be implemented by concrete types, not anonymous structs with function fields
• Test Organization: Shared test helpers reduce duplication and improve maintainability
• Dependency Injection: Using interfaces makes code more testable but requires proper mock implementation