🧭 Epic — Dynamic Configuration UI & Admin API

On first start, this will use .env. After that, it will copy those settings to the database, and allow you to override them from /admin UI / APIs. Not all settings will be exposed. - for example, security settings are only available through the env.

Implements UI features for #738

🧭 Type of Feature

• Admin UX
• Reliability / DevOps
• Security (audit trail)

🙋‍♂️ User Stories

📐 Design Sketch

flowchart TD
    UI[Admin UI Config Tab] -->|GET/PUT| ADMINAPI[/admin/config admin JWT/]
    CI[CLI or CI job] -->|REST| ADMINAPI
    ADMINAPI --> CONFIGSV[ConfigService]
    CONFIGSV --> DB[(configuration table)]
    DB -->|NOTIFY| RELOAD[Reload Daemon]
    RELOAD --> CACHE[in-mem cache]
    CACHE --> APP[App Logic]

    classDef db fill:#ffd1dc
    class DB db

🔄 Roll-out Plan

🔧 Task Breakdown

1. Schema & Seed

   • configuration (key PK, value TEXT, type ENUM, source ENUM, updated_at).
   • config_audit (id, key, old, new, user_id, ts).
   • Migration script that imports _env vars as source='env'.

2. Service Layer

   • ConfigService.get(key), .set(key, value, user), .all().
   • JSONSchema per key (leverages Validation epic).
   • Upsert triggers NOTIFY config_changed.

3. Hot-Reload Daemon

   • BackgroundTask subscribes to config_changed; updates in-mem cache.
   • Fallback: full refresh every 5 min.

4. Admin API

   • GET /admin/config (list, filter by source or prefix).
   • PUT /admin/config/{key} (body: {value}) → returns new revision.
   • RBAC: only platform_admin group.

5. Admin UI (React)

   • New sidebar tab “Configuration”.
   • Table with search, inline edit + JSON/YAML modal for complex types.
   • Badge colour ⇒ source (env = grey, db = green).
   • Toast & websocket push when someone else edits a value.

6. CLI Tooling

   • mcpctl config list | get | set KEY VALUE.
   • Baked into CI deploy job to bump feature flags.

7. Validation & Audit

   • Re-use existing Pydantic validators; reject bad type / range.
   • config_audit endpoint & UI timeline component.

8. Docs & Run-books

   • “Making a setting dynamic” guide (add to schema, seed default).
   • Incident SOP: “How to roll back via audit diff.”

9. Tests

   • Unit: set → get round-trip, wrong type → 422.
   • Integration: two nodes; edit on node A, see updated value on node B in ≤30 s.

🔄 Alternatives Considered

📓 Additional Context

• Precedence: DB → ENV → CODE DEFAULT. If a key exists in DB it always wins.
• Safety Net: Certain immutable keys (e.g. JWT_SIGNING_KEY) flagged locked=true; UI blocks edits.
• Observability: config_reload_seconds histogram; alert if reload fails.
• Back-out: Flip feature flag or delete DB row → node falls back to .env.

Delivering this epic means: ops can toggle limits, feature flags, banners, and branding instantly from the UI or CI without touching Kubernetes manifests or waiting for redeploys—all with validation, RBAC, and full audit history.