---
description: Create new adapter/service type with port interface
---

# New Adapter Creation

Create a **brand new service type** with port interface and first adapter implementation.

## When to Use

**Use this when:**
- Creating first adapter for a service (e.g., first payment adapter with Stripe)
- No port interface exists yet in `internal/domains/ports/`
- Need complete service infrastructure (port + adapter + config + init)

**Already have port?** → Use `/venturo-go:add-adapter-impl`

## Workflow

### Interactive Discovery

Ask these questions:

1. **Adapter type** (Email, Storage, Queue, Cache, Search, Payment, Notification, Other)
2. **Specific provider** (e.g., "SendGrid", "AWS S3", "Stripe")
3. **Port interface exists?** (Check `internal/domains/ports/`)
4. **Core operations** (methods to implement)
5. **Configuration needed** (API keys, endpoints, regions)
6. **Async processing?** (RabbitMQ integration)

Present complete plan before implementation.

### Implementation Steps

1. **Create Port Interface** (if needed) - `internal/domains/ports/{service}.go`
2. **Create Adapter Package** - `pkg/{service}/{provider}/`
3. **Adapter Configuration** - `config.go`
4. **Implement Adapter** - `adapter.go`
5. **Error Handling** - `errors.go`
6. **Main Config Update** - `internal/config/config.go`
7. **Environment Variables** - `.env.example`
8. **Initialization Function** - `pkg/{service}/main.{service}.go`
9. **Application Integration** - `cmd/api/main.go`
10. **Write Tests** - `adapter_test.go`, `integration_test.go`
11. **Documentation** - `README.md`
12. **Optional Async** - AMQP wrapper (see `/venturo-go:add-amqp`)

### Common Port Patterns

**Email Port:**
```go
type EmailService interface {
    SendEmail(to, subject, body string) error
    SendHTMLEmail(to, subject, htmlBody string) error
}
```

**Storage Port:**
```go
type StorageService interface {
    UploadFile(ctx context.Context, path string, data io.Reader) (string, error)
    DownloadFile(ctx context.Context, path string) (io.ReadCloser, error)
    DeleteFile(ctx context.Context, path string) error
}
```

**Payment Port:**
```go
type PaymentService interface {
    CreatePayment(ctx context.Context, amount int64, currency string) (*PaymentResult, error)
    RefundPayment(ctx context.Context, paymentID string) error
}
```

## Adapter Patterns

**HTTP API-Based** (SendGrid, Mailgun, Stripe):
- Use `http.Client`
- Build requests with authentication headers

**SDK-Based** (AWS, Google Cloud):
- Use provider's official SDK client
- Initialize with credentials

**Connection Pool** (Redis, Database):
- Maintain connection pool
- Implement `Close()` method

## Example

```
User: /venturo-go:new-adapter

Claude: What type of adapter? (Email, Storage, Payment...)

User: Payment

Claude: Specific provider?

User: Stripe

Claude: Checking for payment port... Not found.

I'll create:
1. internal/domains/ports/payment.go (interface)
2. pkg/payment/stripe/ (adapter)
3. pkg/payment/main.payment.go (init)

[Proceeds with implementation]
```

## Tips

- Study existing adapters (`pkg/email/gomail/`)
- Follow port interface strictly
- Validate config early, fail fast
- Wrap provider errors with context
- Keep adapters thin
- Never log sensitive data