Overview

This service exposes two APIs:

• Create user: POST /api/v1/users with name, email, password, age?
• Create order: POST /api/v1/orders with user_id, item, category, price

When an order is created, a background job analyzes and stores the user's interests using OpenAI.

Data Model

• users: core user profile, includes age for personalization
• orders: normalized orders table with indexes on (user_id, category)
• user_interests: 1:1 with user, contains summary and properties (JSON)

Layers

• Controller: thin HTTP entry points
• Request: validation layer
• Resource: response mapping
• Service: business logic
• Repository: persistence logic
• Job: async workflows and retries
• External Service: OpenAIClientService encapsulates HTTP calls

Flow

1. POST /api/v1/users validates input, delegates to UserService, returns UserResource.
2. POST /api/v1/orders validates input, OrderService creates order and dispatches AnalyzeUserInterests job.
3. Job loads user, calls UserInterestAnalysisService.
4. UserInterestAnalysisService crafts strict JSON prompt and calls OpenAIClientService.
5. Parsed JSON is upserted into user_interests.

Design Choices

• Separation of concerns via controller/service/repository keeps controllers slim and logic testable.
• Async analysis improves latency and availability; failures are retried with exponential backoff.
• Unique job per user_id prevents thundering herds from rapid order creation.
• Strict JSON prompt and parser reduce schema drift and improve durability of stored data.
• Minimal columns loaded during job for efficiency; appropriate indexes to optimize queries.

Consistency, Stability, Durability, Availability

• Consistency: single-writer per user via ShouldBeUnique; upsert ensures eventual consistency of interests.
• Stability: bounded retries with backoff, structured logging, and explicit error handling.
• Durability: DB transactions handled by Eloquent; idempotent upsert prevents duplication.
• Availability: async background processing decouples API from OpenAI dependency.

Queues and Retries

• Job: AnalyzeUserInterests with tries=5 and progressive backoff.
• Queue name analysis allows dedicated workers and tuning.

Configuration

Add to .env:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_TIMEOUT=15
QUEUE_CONNECTION=database

Run migrations and start workers:

php artisan migrate --graceful
php artisan queue:work --queue=analysis --max-time=3600 --tries=5

Testing

• Validate controllers with request tests.
• Stub OpenAIClientService to return a consistent JSON payload.