mosaic: Instructions file for Codex

Project Instructions

You are working on a production-grade Go codebase that follows strict Hexagonal Architecture (Ports & Adapters).

Your Responsibilities as an Agent

• Strictly adhere to architectural rules, coding standards, and best practices. Never cut corners.
• Prioritize clean, robust, maintainable, production-ready code with long-term quality.
• Refactor messy or unclear solutions properly. Security, testability, and separation of concerns are non-negotiable.

---

Hexagonal Architecture

This project uses Hexagonal Architecture (also known as Ports & Adapters), originally introduced by Alistair Cockburn.

Core Concepts

• The domain is the heart of the application and must remain completely independent.
• All dependencies point inward toward the domain.
• External concerns (databases, HTTP, third-party APIs, etc.) are pushed to the edges as adapters.
• The core business logic is decoupled from frameworks, databases, and delivery mechanisms.

Layer Responsibilities & Rules

• core/domain/ — Pure business entities, value objects, and domain rules. Must have zero dependencies on any other internal package.

• core/ports/ — Defines clean interfaces (contracts).

  • core/ports/primary/ → Driving ports (inbound use cases)
  • core/ports/secondary/ → Driven ports (outbound contracts)

• core/services/ — Application services that implement use cases. Depends only on core/domain/ and core/ports/.

• adapter/ — Concrete implementations of ports.

  • adapter/primary/ → Inbound (HTTP, CLI, gRPC, etc.)
  • adapter/secondary/ → Outbound (databases, external APIs, cache, etc.)

• config/ — Centralized configuration structures and loading.

Strict Rules

• Never import adapter/ from core/domain/, core/ports/, or core/services/
• Never import core/services/ from core/domain/ or core/ports/
• core/domain/ must remain pure at all times
• All external interactions must go through ports
• Follow .golangci.yml (especially depguard rules)