# go-patterns

> Idiomatic Go coding standards, Clean Architecture structure, and best practices for Fiber and Ent. Use when writing or refactoring Go code.

- Author: Hakos
- Repository: hakos47/eonexus-skills
- Version: 20260124135619
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/hakos47/eonexus-skills
- Web: https://mule.run/skillshub/@@hakos47/eonexus-skills~go-patterns:20260124135619

---

---
name: go-patterns
description: Idiomatic Go coding standards, Clean Architecture structure, and best practices for Fiber and Ent. Use when writing or refactoring Go code.
---

# Go Patterns & Clean Architecture

## Overview
This skill defines the standard development patterns for the **Voura** project (formerly Youcards). The project follows **Clean Architecture** with a **Vertical Slice** organization for features.

**Tech Stack:**
- **Language:** Go 1.22+
- **Web Framework:** Fiber v3
- **ORM:** Ent
- **Database:** PostgreSQL

## Project Structure

The project is organized to separate concerns and decouple business logic from infrastructure.

```
api-go/
├── cmd/
│   └── api/                # Application entry point (main.go)
├── internal/
│   ├── domain/             # Business Logic (Pure Go)
│   │   ├── user/           # User Feature
│   │   │   ├── entity.go   # Domain Models
│   │   │   ├── repository.go # Repository Interfaces
│   │   │   └── service.go  # Business Logic Interfaces & Impl
│   │   ├── card/           # Card Feature
│   │   └── ...
│   ├── infrastructure/     # Implementation details
│   │   ├── ent/            # Generated Ent Code
│   │   ├── persistence/    # Repository Implementations (Ent)
│   │   │   ├── user_repository.go
│   │   │   └── ...
│   │   └── server/         # HTTP Server setup
│   └── application/        # Application Services / Use Cases (Optional, often merged into domain services in simpler setups)
```

## Core Principles

### 1. Clean Architecture Layers
- **Domain Layer:** Contains enterprise logic and entities. **MUST NOT** depend on `infrastructure`, `fiber`, or `ent`. It defines interfaces (`Repository`) that infrastructure layers implement.
- **Infrastructure Layer:** Implements interfaces defined in Domain. Depends on external libraries (Ent, Fiber, Redis).
- **Presentation Layer (Handlers):** Handles HTTP requests, converts them to domain objects, calls services, and formats responses.

### 2. Error Handling
- Use the standard `if err != nil` pattern.
- Wrap errors with context when bubbling up: `fmt.Errorf("failed to create user: %w", err)`.
- Use custom error types in the Domain layer to avoid leaking infrastructure details (e.g., `ErrUserNotFound` instead of `ent.NotFoundError`).

### 3. Dependency Injection
- Use **Constructor Injection**.
- Services should depend on Interfaces, not concrete types.

```go
// Good
type UserService struct {
    repo domain.UserRepository
}
func NewUserService(repo domain.UserRepository) *UserService {
    return &UserService{repo: repo}
}
```

## Specific Guides

### Ent ORM (Database)
For schema definitions, migrations, and query patterns, see [Ent Schema Design Patterns](references/ent-schema.md).

### Fiber (HTTP)
For handlers, middleware, and routing, see [Fiber Framework Guide](references/fiber-guide.md).

## Implementation Checklist
When implementing a new feature (e.g., "Card"):

1.  **Domain:** Define `Card` struct in `internal/domain/card/entity.go`.
2.  **Interface:** Define `Repository` and `Service` interfaces in `internal/domain/card/repository.go` and `service.go`.
3.  **Schema:** Create Ent schema in `internal/infrastructure/ent/schema/card.go` (See [Ent Guide](references/ent-schema.md)).
4.  **Persistence:** Implement `Repository` using Ent in `internal/infrastructure/persistence/card_repository.go`.
5.  **Service:** Implement business logic in `internal/domain/card/service.go`.
6.  **Handler:** Create Fiber handler in `internal/infrastructure/http/handlers/card_handler.go` (See [Fiber Guide](references/fiber-guide.md)).
7.  **Route:** Register routes in `cmd/api` or a central router.

## Testing
- Write Unit Tests for Domain Services using Mocks for Repositories.
- Use `testify/mock` or standard Go interfaces for mocking.