Designing Configurable Systems That Don’t Collapse in Production

Most configurable systems fail because they allow too much freedom without structure.

You need constraints.

Core Principles

• Config is data, not logic
• Schema is mandatory
• Defaults must exist
• Overrides must be traceable

1. Define a strict schema

Avoid arbitrary key-value structures.

Use TypeScript or JSON schema:

type FeatureConfig = {
  enabled: boolean;
  retryCount: number;
  timeoutMs: number;
};

2. Layer your config

Do not rely on a single config.

Use layers:

• Default
• Environment
• Customer

Merge order: default → env → customer

3. Version your config

Add versioning:

{
  "version": 2,
  "features": {}
}

Handle old versions explicitly.

4. Validate at boundaries

Validate:

• On write (admin)
• On read (runtime)

Fail fast.

5. Build controlled admin UI

Avoid raw JSON editing.

Use:

• Dropdowns
• Input constraints
• Clear forms

6. Audit changes

Track:

• Who changed
• What changed
• When

7. Cache with invalidation

• Cache config in memory
• Invalidate on update
• Use TTL fallback

When NOT to use config

• Core business logic
• Security rules
• Complex workflows

If config becomes hard to read, you have overdone it.