# GitHub Copilot Instructions for Go Cart Actor

This repository contains a distributed cart management system implemented in Go using the actor model pattern. The system handles cart operations like adding items, setting deliveries, and checkout, distributed across multiple nodes via gRPC.

## Project Structure
- `cmd/`: Entry points for the application.
- `pkg/`: Core packages including grain logic, pools, and HTTP handlers.
- `proto/`: Protocol Buffer definitions for messages and services.
- `api-tests/`: Tests for the HTTP API.
- `deployment/`: Deployment configurations.
- `k6/`: Load testing scripts.

## Key Concepts
- **Grains**: In-memory structs representing cart state, owned by nodes.
- **Pools**: Local and synced pools manage grains and handle ownership.
- **Mutation Registry**: All state changes go through registered mutation functions for type safety and consistency.
- **Ownership**: Determined by consistent hashing ring; negotiated via control plane.

## Coding Guidelines
- Follow standard Go conventions (gofmt, go vet, golint).
- Never say "your right", just be correct and clear.
- Don't edit the *.gb.go files manually, they are generated by the proto files.
- Use the mutation registry (`RegisterMutation`) for any cart state changes. Do not mutate grain state directly outside registered handlers.
- Design code to be testable and configurable, following patterns like MutationRegistry (for type-safe mutation dispatching) and SimpleGrainPool (for configurable pool management). Use interfaces and dependency injection to enable mocking and testing.
- After modifying `.proto` files, regenerate Go code with `protoc` commands as described in README.md. Never edit generated `.pb.go` files manually.
- Use meaningful variable names and add comments for complex logic.
- Handle errors explicitly; use Go's error handling patterns.
- For HTTP endpoints, ensure proper cookie handling for cart IDs.
- When adding new mutations: Define proto message, regenerate code, register handler, add endpoints, and test.
- Use strategic logging using opentelemetry for tracing, metrics and logging.
- Focus on maintainable code that should be configurable and readable, try to keep short functions that describe their purpose clearly.

## Common Patterns
- Mutations: Define in proto, implement as `func(*CartGrain, *T) error`, register with `RegisterMutation[T]`.
- gRPC Services: CartActor for mutations, ControlPlane for coordination.
- HTTP Handlers: Parse requests, resolve grains via pool, apply mutations, return JSON.

## Avoid
- Direct state mutations outside the registry.
- Hardcoding values; use configuration or constants.
- Ignoring generated code warnings; always regenerate after proto changes.
- Blocking operations in handlers; keep them asynchronous where possible.

## Testing
- Write unit tests for mutations and handlers.
- Use integration tests for API endpoints.
- Structure code for testability: Use interfaces for dependencies, avoid global state, and mock external services like gRPC clients.
- Run `go test ./...` to ensure all tests pass.

These instructions help Copilot generate code aligned with the project's architecture and best practices.