opencoverage copilot-instructions.md

Copilot Instructions for coverage-api

Never commit generated code, all code must be manually reviewed and edited as needed to fit architecture and style guidelines. Always follow the architecture and coding standards defined in copilot-instructions.md.

Mission

Build and evolve a Go REST API for coverage ingestion and comparison using Hexagonal Architecture, clean boundaries, and production-grade engineering practices.

Core Architecture: Hexagonal (Ports and Adapters)

Always organize code by domain boundaries and dependency direction.

1. Domain is at the center and knows nothing about frameworks, transport, or databases.
2. Application layer orchestrates use cases and depends only on domain + ports.
3. Adapters implement ports for HTTP, PostgreSQL, auth, and observability.
4. Dependencies point inward only.

Required Layers

Use this structure (or equivalent naming):

• cmd/api - entrypoint and bootstrap wiring
• internal/domain - entities, value objects, domain services, domain errors
• internal/application - use cases and port interfaces
• internal/adapters/http - handlers, request/response DTOs, middleware
• internal/adapters/postgres - repository implementations
• internal/adapters/auth - API key validation adapter
• internal/platform - config, logger, metrics, tracing, db client, clock/uuid abstractions

Do not place business rules in handlers, SQL repositories, or middleware.

Go Language Standards

1. Target the current stable Go version used by the project.
2. Keep packages cohesive and small.
3. Prefer composition over inheritance-like patterns.
4. Return errors, do not panic in normal control flow.
5. Wrap errors with context using fmt.Errorf("...: %w", err).
6. Keep interfaces near the consumer (application ports), not global interface files.
7. Accept context.Context as first parameter for request-scoped operations.
8. Avoid package-level mutable state.
9. Keep functions short and intention-revealing.
10. Use constructor functions with explicit dependencies.