Backend - Identity&Personalization Block

Backend only. No frontend screens are included.

Features

• JWT-style session authentication — signup, login, logout, and token revocation with SHA-256 hashed token storage
• Profile & preferences management — partial updates supported; built-in completion scoring (percent + missing[]) for onboarding checklists
• Media record tracking — stores metadata (URL, type, size, purpose) for files hosted on external storage (S3, Cloudinary, etc.)
• Intake questionnaire upsert — batch save/overwrite answers by question_key; supports strings, numbers, booleans, arrays, and null
• Deterministic style-profile generation — fully reproducible output from preferences + intake answers + media refs; no randomness, no external AI calls
• Visual analysis enrichment endpoint — additive, non-destructive tag merging for plugin-supplied vision results
• Admin API — paginated user listing with completion scores, full user detail view, status toggling (with session revocation), and style profile inspection
• Idempotent SQLite schema — auto-created on boot via better-sqlite3; no migration tooling required
• Demo seed data — auto-seeded on first boot with two users and a complete demo flow; safe across restarts

Tech Stack

Setup & Usage

Install & Run

npm install
npm run dev          # Development mode with ts-node, auto-seeds on first boot

# Or build and run
npm run build && npm start

Health Check

curl -s http://localhost:3000/api/health
# => {"status":"ok","block":"identity-personalization-backend"}

Environment Variables

Seed Credentials

Auto-seeded on boot (idempotent — existing rows are never overwritten):

API Endpoints

Base URL: http://localhost:3000
Auth header (all authenticated routes): Authorization: Bearer <session.token>
Error format: { "error": "...", "field": "..." } with 400, 401, 403, or 404 as appropriate.

Auth — /api/auth

# Signup
curl -s -X POST http://localhost:3000/api/auth/signup \
  -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","password":"wonder123","full_name":"Alice"}'

# Login
curl -s -X POST http://localhost:3000/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"user@example.com","password":"demoPass123"}'

# Current user
curl -s http://localhost:3000/api/auth/me \
  -H "Authorization: Bearer $TOKEN"

# Logout
curl -s -X POST http://localhost:3000/api/auth/logout \
  -H "Authorization: Bearer $TOKEN"

Profile & Preferences — /api/users/me

# Get profile with completion score
curl -s http://localhost:3000/api/users/me/profile \
  -H "Authorization: Bearer $TOKEN"

# Update preferences (all fields optional)
curl -s -X PUT http://localhost:3000/api/users/me/preferences \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
        "height": 175, "weight": 70, "preferred_size": "M",
        "style_preferences": ["minimalist","smart_casual"],
        "color_preferences": ["navy","white","olive"],
        "budget_min": 50, "budget_max": 250
      }'

Media — /api/users/me/media

Stores metadata only — wire your own storage provider (S3, Cloudinary, etc.) and POST the resulting URL here.

Constraints:

• Allowed file_type: image/jpeg, image/png, image/webp, image/gif
• Max file_size: 10 MB
• Allowed upload_purpose: reference, avatar, wardrobe

curl -s -X POST http://localhost:3000/api/users/me/media \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
        "file_url": "https://cdn.example.com/ref.png",
        "file_type": "image/png",
        "file_size": 50000,
        "upload_purpose": "reference"
      }'

Intake — /api/users/me/intake

Answers are upserted by question_key — resubmitting the same key overwrites the previous value.

Recognized keys used by the style-profile generator:

Any other question_key is stored but ignored by the generator.

curl -s -X POST http://localhost:3000/api/users/me/intake \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
        "answers": [
          { "question_key": "style_keywords", "answer_value": ["clean","modern"] },
          { "question_key": "fit_preference", "answer_value": "regular" },
          { "question_key": "occasions",      "answer_value": ["work","date_night"] }
        ]
      }'

Style Profile — /api/users/me/style-profile

# Generate
curl -s -X POST http://localhost:3000/api/users/me/style-profile/generate \
  -H "Authorization: Bearer $TOKEN"

# Read
curl -s http://localhost:3000/api/users/me/style-profile \
  -H "Authorization: Bearer $TOKEN"

# Plugin enrichment (called by AI Vision Style Analysis Plugin Block)
curl -s -X POST http://localhost:3000/api/users/me/style-profile/visual-analysis \
  -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
        "summary": "Predominantly cool tones with structured silhouettes.",
        "style_tags": ["tailored"],
        "color_tags": ["charcoal"],
        "occasion_tags": [],
        "avoid_tags": []
      }'

Generation behavior:

• All output tag lists are deduped, lowercased, and sorted alphabetically
• fit_preference comes from the intake key or falls back to a BMI heuristic
• visual_analysis_summary is preserved across regenerations
• Calling generate multiple times with the same inputs produces identical output

Admin — /api/admin

Requires a bearer token for a user with role === 'admin'.

# List users
curl -s "http://localhost:3000/api/admin/users?limit=50" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Disable a user (also revokes their sessions)
curl -s -X PATCH "http://localhost:3000/api/admin/users/$USER_ID/status" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"status":"disabled"}'

Plugin Integration

The AI Vision Style Analysis Plugin Block (sold separately) integrates via a single endpoint contract:

1. Plugin reads user media via GET /api/users/me/media
2. Plugin performs external vision/AI analysis
3. Plugin POSTs structured results to POST /api/users/me/style-profile/visual-analysis

The backend additively merges plugin-supplied tags into the existing style profile (deduped, never destructive) and stores the summary string. The original generated_at timestamp is preserved. This backend block has no AI provider dependency and functions fully without the plugin.

Scope & Intentional Omissions

• No frontend screens or UI components
• No external AI or image analysis calls
• No file upload byte handling — media storage must be handled by a separate storage provider
• No production-grade migration tooling — schema is created idempotently on boot (suitable for demo/prototype; swap getDb() for Postgres in production)

License

Tetrees License