Skip to content

settings-implementation.md

Latest commit

 

History

History
347 lines (266 loc) · 10.8 KB

settings-implementation.md

File metadata and controls

347 lines (266 loc) · 10.8 KB

Settings Management System - Implementation Summary

Task Report

Status: ✅ SUCCESS

Objective Achieved

Implemented a comprehensive settings management system that allows admin users to configure all environment variables and application settings through the UI, with encryption for secrets, complete audit logging, and validation.

Files Created

Backend Files

Models (backend/app/models/)

  1. application_setting.py - ApplicationSetting model with fields for key, value, type, category, encryption flags, validation schema
  2. setting_audit_log.py - SettingAuditLog model for tracking all setting changes with before/after values
  3. init.py - Updated to export new models

Schemas (backend/app/schemas/)

  1. application_setting.py - Pydantic schemas for CRUD operations, responses (with secret masking), bulk updates, export/import
  2. init.py - Updated to export new schemas

Services (backend/app/services/)

  1. settings_service.py - SettingsService with encryption, validation, audit logging, bulk operations, export/import

Core (backend/app/core/)

  1. runtime_settings.py - RuntimeSettings singleton for in-memory caching and type-safe access to settings

API Routes (backend/app/api/v1/routes/)

  1. settings.py - RESTful API endpoints for all settings operations (admin-only access)

API Router (backend/app/api/v1/)

  1. router.py - Updated to include settings routes

Migrations (backend/alembic/versions/)

  1. 20260101_000200_add_settings.py - Alembic migration creating tables and seeding default settings

Documentation (backend/docs/)

  1. SETTINGS_MANAGEMENT.md - Comprehensive usage guide, API reference, security considerations

Frontend Files

Types (frontend/src/types/)

  1. settings.ts - TypeScript interfaces for ApplicationSetting, SettingCategory, SettingAuditLog
  2. index.ts - Updated to export settings types

API Client (frontend/src/lib/)

  1. settings-api.ts - API client functions for all settings operations

Store (frontend/src/stores/)

  1. settings-store.ts - Zustand store for settings state management

Components (frontend/src/components/settings/)

  1. SettingCard.tsx - Individual setting card with edit/reset functionality
  2. CategorySelector.tsx - Category navigation tabs
  3. SettingSearch.tsx - Search component for filtering settings
  4. ExportImportButtons.tsx - Export/Import action buttons
  5. BulkEditor.tsx - Bulk edit dialog for multiple settings
  6. AuditLogTimeline.tsx - Timeline visualization of setting changes

Components (frontend/src/components/ui/)

  1. textarea.tsx - Textarea UI component (required for BulkEditor)

Pages (frontend/src/app/dashboard/settings/)

  1. management/page.tsx - Main settings management dashboard
  2. category/[category]/page.tsx - Category detail page for editing settings
  3. audit/page.tsx - Audit log page with filtering and export
  4. page.tsx - Updated main settings page with admin link to management

Usage Examples

Backend API Usage

# List all settings
curl http://localhost:8000/api/v1/settings \
  -H "Authorization: Bearer <admin_token>"

# Get settings by category
curl http://localhost:8000/api/v1/settings/category/llm \
  -H "Authorization: Bearer <admin_token>"

# Update a setting
curl -X PUT http://localhost:8000/api/v1/settings/llm.temperature \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"value": "0.8", "change_reason": "More creative responses"}'

# Bulk update
curl -X PUT http://localhost:8000/api/v1/settings/bulk \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {"app.debug": "false", "app.log_level": "WARNING"},
    "change_reason": "Production deployment"
  }'

# Export settings
curl -X POST http://localhost:8000/api/v1/settings/export \
  -H "Authorization: Bearer <admin_token>" \
  -o settings-backup.json

# Import settings
curl -X POST "http://localhost:8000/api/v1/settings/import?overwrite=false" \
  -H "Authorization: Bearer <admin_token>" \
  -F "file=@settings-backup.json"

# Get audit log
curl http://localhost:8000/api/v1/settings/llm.temperature/audit?limit=50 \
  -H "Authorization: Bearer <admin_token>"

Frontend Usage

// Import settings API
import {
  getSettings,
  updateSetting,
  bulkUpdateSettings,
  exportSettings,
  importSettings,
  getAuditLog,
} from '@/lib/settings-api'

// Or use the store
import { useSettingsStore } from '@/stores/settings-store'

const {
  settings,
  categories,
  fetchSettings,
  updateSetting,
  bulkUpdateSettings,
  exportSettings,
  importSettings,
  fetchAuditLog,
} = useSettingsStore()

// Load settings
await fetchSettings('llm')

// Update setting
await updateSetting('llm.temperature', '0.8', 'More creative responses')

// Bulk update
await bulkUpdateSettings({
  'app.debug': 'false',
  'app.log_level': 'WARNING',
}, 'Production deployment')

// Export
const blob = await exportSettings()

// Import
await importSettings(file, false)

// Get audit log
const logs = await fetchAuditLog('llm.temperature', 50)

Runtime Settings Usage (Backend)

from app.core.runtime_settings import get_runtime_settings

settings = get_runtime_settings()

# Get typed values
temperature = settings.get_float("llm.temperature", 0.7)
debug = settings.get_bool("app.debug", False)
max_tokens = settings.get_int("llm.max_tokens", 4096)
cors_origins = settings.get_json("security.cors_origins", [])

# Refresh cache
await settings.refresh()

Security Considerations

1. Encryption

  • All secret values encrypted using Fernet encryption
  • Encryption key required via ENCRYPTION_KEY environment variable
  • Generate key: cryptography.fernet.Fernet.generate_key()
  • Secrets masked in API responses: sk_•••••••••••••••••••••
  • Secrets only decrypted when explicitly requested

2. Access Control

  • Admin-only access: Only admin and superadmin roles can access settings
  • Role verification: Every endpoint checks user role
  • Audit trail: All changes logged with user ID and timestamp

3. Validation

  • Server-side validation for all inputs
  • Type validation (integer, float, boolean, json)
  • Schema validation using JSON Schema
  • Range validation (min/max)
  • Enum validation for predefined values

4. Audit Trail

  • Immutable audit log in setting_audit_logs table
  • Records: old value, new value, user, timestamp, reason
  • Export capability for compliance
  • No delete/update operations on audit logs

5. Best Practices

  • Change reasons recommended for audit trail
  • Test in development before production
  • Export before bulk changes (backup)
  • Review audit logs regularly
  • Rotate ENCRYPTION_KEY periodically

Integration Points

1. Existing Services

Update services to use runtime settings:

# Before
from app.core.settings import get_settings
settings = get_settings()
temp = settings.llm_temperature

# After
from app.core.runtime_settings import get_runtime_settings
runtime = get_runtime_settings()
temp = runtime.get_float("llm.temperature", 0.7)

2. Database Service

# Use settings from DB instead of env vars
pool_size = runtime_settings.get_int("database.pool_size", 10)
pool_timeout = runtime_settings.get_int("database.pool_timeout", 30)
echo_sql = runtime_settings.get_bool("database.echo_sql", False)

3. LLM Client

# Use dynamic settings
temperature = runtime_settings.get_float("llm.temperature", 0.7)
max_tokens = runtime_settings.get_int("llm.max_tokens", 4096)
api_key = runtime_settings.get_string("llm.openai_api_key")

4. Security Settings

# Use dynamic security settings
jwt_expiry = runtime_settings.get_int("security.jwt_expiry_minutes", 30)
max_attempts = runtime_settings.get_int("security.max_login_attempts", 5)
cors_origins = runtime_settings.get_json("security.cors_origins", [])

5. WebSocket Events (Future)

# Emit events on settings change
await websocket_manager.broadcast({
    "type": "settings_updated",
    "setting_key": key,
    "updated_by": user_id,
    "timestamp": datetime.now(timezone.utc).isoformat(),
})

Migration

Run migration to create tables and seed defaults:

cd backend
alembic upgrade head

This creates:

  1. application_settings table with indexes
  2. setting_audit_logs table with foreign keys
  3. Seeds 23 default settings across 6 categories

Setting Categories & Defaults

LLM (7 settings)

  • llm.default_provider, llm.openai_api_key, llm.openai_base_url
  • llm.anthropic_api_key, llm.groq_api_key
  • llm.temperature, llm.max_tokens

Database (3 settings)

  • database.pool_size, database.pool_timeout, database.echo_sql

Redis (2 settings)

  • redis.db, redis.ttl

Security (4 settings)

  • security.jwt_expiry_minutes, security.max_login_attempts
  • security.session_timeout_minutes, security.cors_origins

Application (4 settings)

  • app.debug, app.log_level, app.workers, app.max_upload_size_mb

UI (3 settings)

  • ui.theme, ui.page_size, ui.enable_websocket

Warnings & Gotchas

  1. ENCRYPTION_KEY Required: Must set before using secret settings

    # Generate and set
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
export ENCRYPTION_KEY="<generated_key>"

  2. Admin Access Only: Regular users will get 403 Forbidden

  3. Restart May Be Required: Some settings (workers, database pool) may require application restart

  4. Validation Errors: Check validation schema if updates fail

  5. Audit Log Growth: Consider periodic export/archival for compliance

Assumptions

  1. PostgreSQL database is configured and accessible
  2. Redis is available for caching (optional)
  3. User authentication and RBAC system is in place
  4. Admin/superadmin roles exist in the system
  5. Alembic migrations are configured and working
  6. Frontend has Next.js with App Router configured
  7. Zustand is used for state management
  8. shadcn/ui components are available

Files Modified

  1. backend/app/models/init.py - Added exports for new models
  2. backend/app/schemas/init.py - Added exports for new schemas
  3. backend/app/services/init.py - Added exports for settings service
  4. backend/app/api/v1/router.py - Added settings routes
  5. frontend/src/types/index.ts - Added settings type exports
  6. frontend/src/app/dashboard/settings/page.tsx - Added admin link to management page

Next Steps

  1. Run migration: alembic upgrade head
  2. Generate encryption key and set ENCRYPTION_KEY environment variable
  3. Restart backend to load runtime settings
  4. Test settings UI at /dashboard/settings/management
  5. Update existing services to use runtime settings
  6. Add WebSocket events for real-time updates
  7. Consider adding approval workflow for critical settings