defaults-plus-overrides

Defaults Plus Overrides

Category: Architecture Time Saved: 2+ hours avoiding configuration complexity Battle-tested: Yes — user preference systems, role-based config

---

The Problem

You're building a system with configurable behavior — user preferences, role-based permissions, or tenant-specific settings. You need sensible defaults but also flexibility. You end up with either rigid presets OR overwhelming configuration options.

Why It's Hard

• Too rigid: Users can't customize what they need
• Too flexible: Users must configure everything
• Presets only: Edge cases require workarounds
• Full config: Decision fatigue, misconfiguration risk

The Rule

Provide role/archetype defaults, allow partial overrides, clamp to safe bounds.

The Pattern

Archetype Default + User Overrides + Bounds Clamping = Final Config

Step 1: Define Archetypes

const ARCHETYPES = {
  developer: {
    verbosity: 'detailed',
    theme: 'dark',
    shortcuts: true,
    maxTokens: 4000,
    autoSave: true,
  },
  executive: {
    verbosity: 'concise',
    theme: 'light',
    shortcuts: false,
    maxTokens: 1000,
    autoSave: false,
  },
  researcher: {
    verbosity: 'detailed',
    theme: 'auto',
    shortcuts: true,
    maxTokens: 8000,
    autoSave: true,
  },
};

Step 2: Define Bounds

const BOUNDS = {
  maxTokens: { min: 100, max: 16000 },
  verbosity: ['concise', 'normal', 'detailed'],
  theme: ['light', 'dark', 'auto'],
};

Step 3: Merge with Clamping

function resolveConfig(archetype, overrides = {}) {
  // Start with archetype defaults
  const base = { ...ARCHETYPES[archetype] };
  
  // Apply user overrides
  const merged = { ...base, ...overrides };
  
  // Clamp to bounds
  return clampConfig(merged, BOUNDS);
}

function clampConfig(config, bounds) {
  const result = { ...config };
  
  for (const [key, constraint] of Object.entries(bounds)) {
    if (constraint.min !== undefined) {
      // Numeric bound
      result[key] = Math.max(constraint.min, Math.min(constraint.max, result[key]));
    } else if (Array.isArray(constraint)) {
      // Enum bound
      if (!constraint.includes(result[key])) {
        result[key] = constraint[0]; // Default to first option
      }
    }
  }
  
  return result;
}