headquarter/openspec/changes/archive/2025-05-18-user-config-management/design.md

Context

The platform needs a simple key-value configuration system for user preferences like theme, editor, and git identity.

Goals / Non-Goals

Goals:

• Store user config as JSONB in PostgreSQL
• Support partial updates (PATCH semantics)
• Apply theme in frontend on load
• Provide settings UI

Non-Goals:

• Complex nested config structures
• Config validation beyond type checking
• Per-project config (global only)

Decisions

1. JSONB column for flexibility

   • Rationale: Simple key-value, no schema migrations for new keys

2. Merge semantics for updates

   • Rationale: Frontend can update single key without sending entire config

3. Lazy creation

   • Rationale: Config row created on first write, not on user creation

Risks

• [JSONB query performance] → Only querying by user_id, not by config keys
• [No schema validation] → Frontend validates known keys, backend accepts any JSON