pantry

pantry - Built with Hexagonal Architecture

Generated by HexaGo - A hexagonal architecture scaffolding CLI tool.

Overview

This project follows the Hexagonal Architecture (also known as Ports & Adapters) pattern, which promotes:

• Clear separation of concerns
• Framework independence in the core domain
• Testability through dependency inversion
• Maintainability and flexibility

Project Structure

pantry/
├── cmd/                         # Application commands (Cobra CLI)
│   ├── root.go                  # Root command and configuration
│   ├── run.go                   # Server startup with graceful shutdown
│   └── migrate.go               # Database migration runner
├── internal/
│   ├── core/                    # CORE - Business logic (no external dependencies)
│   │   ├── domain/              # Domain entities and value objects
│   │   └── services/            # Application business logic
│   ├── adapters/                # ADAPTERS - External interfaces
│   │   ├── primary/             # Inbound adapters (HTTP, gRPC, CLI)
│   │   └── secondary/           # Outbound adapters (database, external APIs)
│   ├── config/                  # Configuration management
│   ├── infrastructure/          # Cross-cutting utilities
│   └── observability/           # Health-check and metrics
├── pkg/                         # Public reusable packages
│   ├── logger/                  # Logger implementation
│   └── server/                  # HTTP server setup
├── main.go                      # Application entry point
├── Makefile                     # Common development tasks
└── README.md                    # This file

Architecture Principles

Dependency Rule

Dependencies flow inward:

Adapters → Core (services) → Domain

• Core Domain never depends on adapters or infrastructure
• Services orchestrate domain logic and define interfaces (ports)
• Adapters implement the interfaces defined by the core

Layers

1. Domain (internal/core/domain/)

   • Pure business entities
   • Value objects
   • Domain logic
   • No external dependencies

2. Services (internal/core/services/)

   • Application business logic
   • Orchestrates domain objects
   • Defines port interfaces
   • Framework-agnostic

3. Adapters (internal/adapters/)

   • Primary: Handle incoming requests (HTTP handlers, gRPC, CLI)
   • Secondary: Handle outgoing calls (databases, external APIs)

4. Infrastructure (internal/config/, internal/infrastructure/)

   • Configuration
   • Cross-cutting utilities

5. Observability (internal/observability/)

   • Health-check endpoints
   • Prometheus metrics

6. Shared packages (pkg/)

   • Public reusable packages
   • HTTP server setup
   • Logger implementation

Getting Started

Prerequisites

• Go 1.21+ installed
• Make (optional, for convenience commands)
• Docker and Docker Compose (for containerized deployment)

Installation

# Install dependencies
go mod download

# Build the application
make build
# or
go build -o pantry main.go

Running

# Run directly
./pantry run

# Or using go run
go run main.go run

# Or using make
make run

The server will start on port 8080 (configurable via config file or environment variables).

Configuration

Create a .pantry.yaml file in the project root:

server:
  port: 8080
  host: 0.0.0.0
  readtimeout: 15s
  writetimeout: 15s
  idletimeout: 60s
  shutdowntimeout: 30s

database:
  url: postgres://user:pass@localhost:5432/pantry?sslmode=disable

loglevel: info
logformat: json

Or use environment variables with PANTRY_ prefix:

export PANTRY_SERVER_PORT=8080
export PANTRY_LOGLEVEL=debug
export PANTRY_DATABASE_URL=postgres://user:pass@localhost:5432/pantry?sslmode=disable

Development

Available Commands

make help          # Show all available commands
make build         # Build the application
make run           # Run the application
make test          # Run tests
make test-coverage # Run tests with coverage report
make clean         # Clean build artifacts
make fmt           # Format code
make lint          # Run linter
make mod-tidy      # Tidy go modules
make build-image   # Build Docker image
make docker-up     # Start Docker Compose services
make docker-down   # Stop Docker Compose services
make docker-logs   # View Docker Compose logs
make crap          # Calculates CRAP scoring

Testing

# Run all tests
go test ./...

# Run tests with coverage
go test -v -race -coverprofile=coverage.out ./...

# View coverage report
go tool cover -html=coverage.out

Docker

# Build Docker image
docker build -t pantry:latest .

# Run with Docker Compose
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

API Endpoints

• GET /health - Health check endpoint

Adding New Features

When adding new features, follow the hexagonal architecture:

1. Add domain entities in internal/core/domain/
2. Add business logic in internal/core/services/
3. Add adapters as needed:
   • HTTP handlers in internal/adapters/primary/http/
   • Database repositories in internal/adapters/secondary/database/
4. Add migrations using make migrate or go run main.go migrate

Learn More

• Hexagonal Architecture
• Ports & Adapters Pattern
• Clean Architecture

License

[Your License Here]

Generated by HexaGo

This project was scaffolded using HexaGo, an opinionated CLI tool for generating hexagonal architecture projects.

Learn more: hexago