364 lines
17 KiB
Markdown
364 lines
17 KiB
Markdown
# 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` |
|