go-cart-actor/.github/copilot-instructions.md

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.