# Feature: User Preferences API

## Problem Statement

Users of the platform need a way to persist and retrieve personal preferences (theme, language, notification settings) so their experience is consistent across sessions and devices. Currently, the `preferences-api` service exists as a scaffold with only example CRUD endpoints and no actual preference management capability.

## User Stories

- As an authenticated user, I want to retrieve my preferences so that the UI reflects my saved settings when I log in.
- As an authenticated user, I want to update my preferences so that changes to theme, language, or notification settings are persisted.
- As a frontend application, I want to fetch preferences for the current user so I can apply theme/language/notification configuration on page load.
- As an admin or service, I want to retrieve preferences for a specific user by user ID so I can provide user-specific experiences in server-rendered contexts.

## Acceptance Criteria

- [ ] `GET /api/preferences-api/preferences/{user_id}` returns the user's preferences as a key-value map within the standard `{data, meta}` envelope
- [ ] `PUT /api/preferences-api/preferences/{user_id}` creates or fully replaces the user's preferences (upsert semantics)
- [ ] Both endpoints require authentication via the existing `auth.Middleware()`
- [ ] Authenticated users can only access their own preferences (the `{user_id}` in the URL must match the JWT `UserID`/`Subject`)
- [ ] Preferences are stored as key-value pairs with string keys and JSON-compatible values
- [ ] The following preference keys are supported with validation:
  - `theme`: must be one of `"light"`, `"dark"`, `"system"`
  - `language`: must be a valid BCP-47 language tag (e.g., `"en"`, `"fr"`, `"es"`, `"de"`, `"ja"`)
  - `notifications.email`: must be a boolean
  - `notifications.push`: must be a boolean
  - `notifications.digest`: must be one of `"none"`, `"daily"`, `"weekly"`
- [ ] `GET` for a user with no saved preferences returns a `200` with default values (not a 404)
- [ ] Default preference values: `theme: "system"`, `language: "en"`, `notifications.email: true`, `notifications.push: true`, `notifications.digest: "weekly"`
- [ ] `PUT` with unknown preference keys returns `400 Bad Request` with a descriptive error
- [ ] `PUT` with invalid preference values returns `400 Bad Request` with per-field validation errors
- [ ] Preferences are persisted in PostgreSQL (using the existing `DatabaseConfig`)
- [ ] The domain layer contains pure preference models with validation logic, following hexagonal architecture
- [ ] A `PreferenceRepository` port interface is defined, with a PostgreSQL adapter implementation
- [ ] A `PreferenceService` orchestrates business logic between handler and repository
- [ ] OpenAPI spec is updated to document both endpoints with schemas, examples, and error responses
- [ ] Unit tests cover domain validation, service logic, and handler request/response mapping
- [ ] Integration-style tests verify handler behavior using the in-memory repository adapter
- [ ] The existing example CRUD scaffolding is removed and replaced with preference endpoints

## Technical Constraints

- **Architecture**: Must follow the established hexagonal architecture pattern (domain -> service -> port -> adapter) already present in `services/preferences-api/`
- **URL parameters**: Must use brace syntax `{user_id}` (not `:user_id`) per chi router requirements
- **Request binding**: Must use `app.Bind()` / `app.BindAndValidate()` -- never raw `json.NewDecoder`
- **Error handling**: Handlers return `error`, wrapped with `app.Wrap()`. Use `httperror.BadRequest`, `httperror.NotFound`, `httperror.Forbidden` etc.
- **Response format**: All responses use the `{data, meta}` envelope via `httpresponse.OK`, `httpresponse.Created`, etc.
- **Auth identity**: User identity is extracted from JWT via `auth.GetUser(ctx)` which returns `*auth.User` with an `ID` field
- **Database**: PostgreSQL, connection details via `config.DatabaseConfig` (environment variable `DATABASE_URL`)
- **Port**: The service runs on port 8001 (default)
- **Route prefix**: All routes must be under `/api/preferences-api/` to match ingress routing

## Dependencies

- `pkg/auth` -- JWT middleware and `auth.GetUser()` for extracting authenticated user identity
- `pkg/app` -- `app.Wrap()`, `app.Bind()`, `app.BindAndValidate()` for handler patterns
- `pkg/httperror` -- Typed HTTP error constructors
- `pkg/httpresponse` -- Response envelope helpers
- `pkg/openapi` -- OpenAPI spec builder for documentation
- `pkg/config` -- `DatabaseConfig` for PostgreSQL connection parameters
- PostgreSQL database instance (local dev via `docker-compose` or `scripts/dev.sh`)

## Out of Scope

- **Bulk operations**: No endpoint for fetching/updating preferences for multiple users at once
- **Preference history/audit log**: No versioning or history of preference changes
- **Real-time sync**: No WebSocket or push notification when preferences change on another device
- **Custom/arbitrary preference keys**: Only the defined keys (theme, language, notifications.*) are supported -- extensibility is deferred
- **DELETE endpoint**: Preferences are reset to defaults via `PUT`, not deleted
- **Pagination**: Preferences are a fixed small set per user, no pagination needed
- **Admin override**: No endpoint for admins to modify another user's preferences (admin read is permitted for server-rendered contexts but write is not)

## Open Questions

1. **Admin read access**: Should admin users (identified by a role in JWT) be allowed to read other users' preferences, or should the `{user_id}` always be strictly self-only? The spec currently allows admin read but this needs confirmation.
2. **Preference key extensibility**: Should the API accept and store unknown preference keys (with a max key count limit), or strictly reject them? The spec currently rejects unknown keys.
3. **Partial updates (PATCH)**: Should a `PATCH` endpoint be added for updating individual preference keys without sending the full set, or is `PUT` (full replace) sufficient for MVP?
4. **Rate limiting**: Should preference updates be rate-limited to prevent abuse, or is auth sufficient protection?