# Design: User Preferences API

## Architecture Approach

Replace the example CRUD scaffolding in `services/preferences-api` with a real user preferences domain. All six layers of the hexagonal architecture change:

| Layer | What changes |
|-------|-------------|
| **Domain** | Replace `Example` entity with `UserPreferences` entity. New validation for theme, language, notification fields. |
| **Port** | Replace `ExampleRepository` with `PreferencesRepository` (2 methods: `Get`, `Upsert`). |
| **Adapter** | Add `internal/adapter/postgres/` with a JSONB-backed PostgreSQL implementation. Remove `internal/adapter/memory/`. |
| **Service** | Replace `ExampleService` with `PreferencesService` (2 use cases: `GetPreferences`, `UpdatePreferences`). |
| **Handlers** | Replace example CRUD handlers with `GET /preferences/{user_id}` and `PUT /preferences/{user_id}`. |
| **API** | Update routes and OpenAPI spec. Remove all example endpoint definitions. |

The existing `main.go` wiring, config, and health handler remain. `main.go` changes to connect to PostgreSQL (via `pkg/database`) and run migrations on startup.

### Design Decisions

1. **Return defaults for unknown users (200, not 404):** Simpler frontend DX. The service returns a default `UserPreferences` struct when no row exists.
2. **Reject unknown preference keys:** Use `app.BindAndValidateStrict()` to reject unknown JSON fields. This catches typos and prevents silent data loss. Forward compatibility can be added later when new keys are defined.
3. **Accept any valid UUID for `user_id`:** No inter-service call to validate user existence. The preferences service is a simple key-value store keyed by UUID. This avoids coupling and latency.
4. **JSONB for preferences storage:** Single `preferences` JSONB column for the nested preference object. One row per user. Flexible schema that doesn't require migrations when adding new preference keys in the future.
5. **Deep merge on PUT:** The service performs a deep merge of the incoming JSON with existing preferences. Keys not included in the request body remain unchanged. Nested objects (like `notifications`) are merged recursively, not replaced wholesale.

## Data Model Changes

### New Table: `user_preferences`

```sql
CREATE TABLE IF NOT EXISTS user_preferences (
    user_id     UUID PRIMARY KEY,
    preferences JSONB NOT NULL DEFAULT '{}',
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

Migration file: `services/preferences-api/migrations/001_create_user_preferences.sql`

### Domain Types

```go
// domain/preferences.go

type UserID string

type Preferences struct {
    Theme         string                `json:"theme"`
    Language      string                `json:"language"`
    Notifications NotificationSettings  `json:"notifications"`
}

type NotificationSettings struct {
    Email  bool   `json:"email"`
    Push   bool   `json:"push"`
    Digest string `json:"digest"`
}

type UserPreferences struct {
    UserID      UserID
    Preferences Preferences
    UpdatedAt   time.Time
}
```

### Default Values

```go
func DefaultPreferences() Preferences {
    return Preferences{
        Theme:    "system",
        Language: "en",
        Notifications: NotificationSettings{
            Email:  true,
            Push:   true,
            Digest: "weekly",
        },
    }
}
```

### Domain Validation

Validation lives in the domain layer, called by the service layer before persistence:

```go
func (p *Preferences) Validate() error { ... }
```

| Field | Rule | Error |
|-------|------|-------|
| `theme` | Must be `"light"`, `"dark"`, or `"system"` | `ErrInvalidTheme` |
| `language` | Must be non-empty string | `ErrInvalidLanguage` |
| `notifications.email` | Boolean (validated by JSON binding) | N/A |
| `notifications.push` | Boolean (validated by JSON binding) | N/A |
| `notifications.digest` | Must be `"daily"`, `"weekly"`, or `"never"` | `ErrInvalidDigest` |

## API Changes

### Endpoints

All routes mounted under `/api/preferences-api`.

#### GET `/api/preferences-api/preferences/{user_id}`

Retrieve preferences for a user. Returns defaults if no preferences are stored.

**Path Parameter:**
- `user_id` (UUID, required) - Validated with `uuid.Parse()`

**Response 200:**
```json
{
  "data": {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "preferences": {
      "theme": "dark",
      "language": "en",
      "notifications": {
        "email": true,
        "push": false,
        "digest": "weekly"
      }
    },
    "updated_at": "2026-02-09T12:00:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}
```

**Response 400:** Invalid `user_id` format.

#### PUT `/api/preferences-api/preferences/{user_id}`

Create or update preferences (upsert with deep merge).

**Path Parameter:**
- `user_id` (UUID, required)

**Request Body:**
```json
{
  "preferences": {
    "theme": "light",
    "notifications": {
      "push": true
    }
  }
}
```

Only provided keys are changed. Omitted keys retain their current value (or default if no row exists).

**Response 200:** Full merged preference set after update.

**Response 400:** Invalid `user_id` or invalid preference values.

### Request/Response Types (Handler Layer)

```go
// UpdatePreferencesRequest is the PUT request body.
type UpdatePreferencesRequest struct {
    Preferences PreferencesInput `json:"preferences" validate:"required"`
}

// PreferencesInput uses pointers to distinguish "not provided" from zero values.
type PreferencesInput struct {
    Theme         *string              `json:"theme,omitempty"`
    Language      *string              `json:"language,omitempty"`
    Notifications *NotificationsInput  `json:"notifications,omitempty"`
}

type NotificationsInput struct {
    Email  *bool   `json:"email,omitempty"`
    Push   *bool   `json:"push,omitempty"`
    Digest *string `json:"digest,omitempty"`
}

// PreferencesResponse is the GET/PUT response shape.
type PreferencesResponse struct {
    UserID      string               `json:"user_id"`
    Preferences domain.Preferences   `json:"preferences"`
    UpdatedAt   string               `json:"updated_at"`
}
```

## Component Diagram

```
┌─────────────────────────────────────────────────────────┐
│                     HTTP Client                         │
└────────────┬────────────────────────┬───────────────────┘
             │ GET /preferences/{id}  │ PUT /preferences/{id}
             ▼                        ▼
┌─────────────────────────────────────────────────────────┐
│  api/routes.go                                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │  app.Wrap(handler.Get)   app.Wrap(handler.Upsert) │  │
│  └───────────────────────────────────────────────────┘  │
└────────────┬────────────────────────┬───────────────────┘
             │                        │
             ▼                        ▼
┌─────────────────────────────────────────────────────────┐
│  handlers/preferences.go                                │
│  - Validates user_id (UUID parse)                       │
│  - Binds & validates request body                       │
│  - Calls service layer                                  │
│  - Maps domain errors → httperror                       │
│  - Returns httpresponse.OK(w, r, response)              │
└────────────┬────────────────────────┬───────────────────┘
             │                        │
             ▼                        ▼
┌─────────────────────────────────────────────────────────┐
│  service/preferences.go                                 │
│  - GetPreferences: repo.Get → defaults if not found     │
│  - UpdatePreferences: repo.Get → merge → validate →     │
│    repo.Upsert                                          │
└────────────┬────────────────────────┬───────────────────┘
             │                        │
             ▼                        ▼
┌─────────────────────────────────────────────────────────┐
│  port/preferences.go (interface)                        │
│  - Get(ctx, userID) → (*UserPreferences, error)         │
│  - Upsert(ctx, *UserPreferences) → error                │
└────────────┬────────────────────────┬───────────────────┘
             │                        │
             ▼                        ▼
┌─────────────────────────────────────────────────────────┐
│  adapter/postgres/preferences.go                        │
│  - Get: SELECT ... WHERE user_id = $1                   │
│  - Upsert: INSERT ... ON CONFLICT (user_id) DO UPDATE   │
│  Uses *database.Pool (sqlx)                             │
└────────────┬────────────────────────┬───────────────────┘
             │                        │
             ▼                        ▼
┌─────────────────────────────────────────────────────────┐
│  PostgreSQL: user_preferences table                     │
│  (user_id UUID PK, preferences JSONB, timestamps)       │
└─────────────────────────────────────────────────────────┘
```

## Error Handling Strategy

### Domain Errors

```go
var (
    ErrInvalidTheme    = errors.New("invalid theme: must be light, dark, or system")
    ErrInvalidLanguage = errors.New("invalid language: must be non-empty")
    ErrInvalidDigest   = errors.New("invalid digest: must be daily, weekly, or never")
)
```

### Error Mapping (handler layer)

| Domain Error | HTTP Error | Status |
|-------------|-----------|--------|
| `ErrInvalidTheme` | `httperror.BadRequest(msg)` | 400 |
| `ErrInvalidLanguage` | `httperror.BadRequest(msg)` | 400 |
| `ErrInvalidDigest` | `httperror.BadRequest(msg)` | 400 |
| Invalid UUID (user_id) | `httperror.BadRequest("invalid user_id format")` | 400 |
| Request body parse error | Handled by `app.BindAndValidate()` | 400 |
| Database connection error | Unhandled → `app.Wrap()` returns 500 | 500 |

### Key Behaviors

- **GET for unknown user:** Returns 200 with default preferences (not 404). No error.
- **PUT with empty body:** Returns 400 via `app.BindAndValidate()` (the `preferences` field is `validate:"required"`).
- **PUT with partial preferences:** Merges with existing. Only validates provided fields.
- **Database errors:** Bubble up as raw errors. `app.Wrap()` converts them to 500.

## Security Considerations

- **No authentication required for this feature** (per spec: auth is out of scope). Routes are public. Auth middleware can be added later via route group.
- **User ID from URL path, not session:** Any caller can read/write any user's preferences. This is intentional — the preferences service is a backend store, not a user-facing endpoint. Upstream services/gateways enforce authorization.
- **Input validation:** All preference values are validated against allowlists. No arbitrary string storage.
- **SQL injection prevention:** All queries use parameterized placeholders (`$1`, `$2`). JSONB values are marshaled by `encoding/json` and passed as parameters.
- **Request body size:** Limited by the framework's default max body size.
- **No sensitive data:** Preferences (theme, language, notifications) contain no PII or secrets.
- **Strict JSON binding:** Unknown fields in the request body are rejected to prevent confusion.

## Performance Considerations

- **Single row per user:** O(1) lookup by UUID primary key. No joins, no pagination needed.
- **JSONB column:** PostgreSQL JSONB is compact and efficient for reads. No need for GIN indexes — we query by `user_id` PK only, never by preference content.
- **No caching layer:** For MVP, direct database reads are sufficient. The query is a simple PK lookup. If latency becomes an issue, an in-memory or Redis cache can be added as a separate adapter behind the same port interface.
- **Upsert atomicity:** `INSERT ... ON CONFLICT DO UPDATE` is a single atomic statement. No race conditions on concurrent writes for the same user.
- **JSONB merge in application layer:** The merge happens in Go, not in SQL. This keeps the SQL simple and the merge logic testable. The full merged JSONB is written back. For this data size (~200 bytes of JSON), this is efficient.
- **Expected load:** Low. Preferences are read on session start and written on settings change. Well within single-instance PostgreSQL capacity.

## Migration / Rollout Plan

### Step 1: Remove Example Scaffolding

Delete all example-related files:
- `internal/domain/example.go`
- `internal/port/example.go`
- `internal/service/example.go`, `example_test.go`
- `internal/api/handlers/example.go`, `example_test.go`
- `internal/adapter/memory/example.go`

Remove example routes and OpenAPI definitions from `routes.go` and `spec.go`.

### Step 2: Add Preferences Domain

Create new files following the same directory structure:
- `internal/domain/preferences.go` — entity, validation, defaults
- `internal/domain/errors.go` — updated with preference-specific errors
- `internal/port/preferences.go` — `PreferencesRepository` interface
- `internal/service/preferences.go` — `PreferencesService` with `GetPreferences` and `UpdatePreferences`
- `internal/service/preferences_test.go` — unit tests with mock repository
- `internal/api/handlers/preferences.go` — HTTP handlers
- `internal/api/handlers/preferences_test.go` — handler tests

### Step 3: Add PostgreSQL Adapter

- `internal/adapter/postgres/preferences.go` — implements `PreferencesRepository`
- `migrations/001_create_user_preferences.sql` — table creation

### Step 4: Update Wiring

- `internal/api/routes.go` — register new preference routes
- `internal/api/spec.go` — new OpenAPI definitions for preference endpoints
- `cmd/server/main.go` — connect to PostgreSQL, run migrations, wire PostgreSQL adapter

### Step 5: Verify

- All unit tests pass (`go test -v ./...`)
- OpenAPI spec exports correctly (`--export-openapi` flag)
- Health endpoint still works
- Manual verification against acceptance criteria

### Backward Compatibility

This is a **breaking replacement** of the example scaffolding, which was never a production API. No backward compatibility is needed. The example endpoints (`/examples`, `/examples/{id}`) are removed entirely.

## File Inventory

| Action | File |
|--------|------|
| **Delete** | `internal/domain/example.go` |
| **Delete** | `internal/port/example.go` |
| **Delete** | `internal/service/example.go` |
| **Delete** | `internal/service/example_test.go` |
| **Delete** | `internal/api/handlers/example.go` |
| **Delete** | `internal/api/handlers/example_test.go` |
| **Delete** | `internal/adapter/memory/example.go` |
| **Modify** | `internal/domain/errors.go` |
| **Modify** | `internal/api/routes.go` |
| **Modify** | `internal/api/spec.go` |
| **Modify** | `cmd/server/main.go` |
| **Create** | `internal/domain/preferences.go` |
| **Create** | `internal/port/preferences.go` |
| **Create** | `internal/service/preferences.go` |
| **Create** | `internal/service/preferences_test.go` |
| **Create** | `internal/api/handlers/preferences.go` |
| **Create** | `internal/api/handlers/preferences_test.go` |
| **Create** | `internal/adapter/postgres/preferences.go` |
| **Create** | `migrations/001_create_user_preferences.sql` |
