Configuration Management API¶

Referenced Files in This Document

Table of Contents¶

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Conclusion
Appendices

Introduction¶

This document provides detailed API documentation for Nexo’s configuration management system. It covers endpoints for reading application settings, updating configuration values, and validating configuration schemas. It explains the hierarchical configuration structure (defaults, environment variable overrides, file-based configuration), configuration categories (processing pipeline, AI classifier parameters, database connections, notification services), bulk update operations, backup/restore workflows, validation rules with error messages, dynamic updates, migration procedures, and security considerations including sensitive data handling and access control.

Project Structure¶

The configuration management spans shared schema definitions, runtime configuration loading, FastAPI route handlers, and UI service integration:

Shared configuration schema and models define the shape and validation rules for all configuration sections.
Runtime configuration loaders implement hierarchy resolution (defaults ? env ? files).
FastAPI routes expose read/update/validation endpoints and orchestrate persistence and notifications.
UI dashboard service integrates with backend configuration APIs to support dynamic updates.

graph TB

subgraph "Shared Layer"

Schemas["schemas/config.py"]

ConfigModel["shared/config.py"]

end

subgraph "Service Layer"

Routes["service/routes/config.py"]

App["service/app.py"]

Deps["service/deps.py"]

end

subgraph "UI Integration"

UISvc["ui/dashboard/services/config_svc.py"]

end

Schemas --> ConfigModel

ConfigModel --> Routes

Routes --> App

Routes --> Deps

UISvc --> Routes

Diagram sources

Section sources

Core Components¶

Configuration Schema Definitions: Typed models and validators that enforce structure and constraints across all configuration categories.
Configuration Loader: Implements hierarchical resolution combining defaults, environment variables, and file-based overrides.
Configuration API Routes: REST endpoints for GET/PUT/PATCH operations, bulk updates, validation, backup, and restore.
Service Dependencies: Centralized dependency injection for configuration access and persistence.
UI Dashboard Service: Client-side helper to call configuration endpoints from the web dashboard.

Key responsibilities:

Provide a single source of truth for configuration structure and validation.
Ensure consistent precedence: defaults < environment variables < file overrides.
Expose safe, validated, and auditable configuration operations via API.
Support dynamic reload without restart where applicable.

Section sources

Architecture Overview¶

The configuration system is layered:

Schema layer defines types and validation rules.
Loader resolves effective configuration at runtime.
API layer exposes endpoints backed by loader and persistence.
UI calls API to reflect changes dynamically.

sequenceDiagram

participant UI as "Dashboard UI"

participant API as "FastAPI Routes"

participant Loader as "Config Loader"

participant Store as "Persistence"

UI->>API : GET /api/config

API->>Loader : load()

Loader-->>API : Effective config

API-->>UI : JSON response

UI->>API : PATCH /api/config

API->>Loader : validate_and_apply(patch)

Loader->>Store : persist_changes()

Store-->>Loader : ok

Loader-->>API : updated config

API-->>UI : 200 OK + new state

Diagram sources

Detailed Component Analysis¶

Configuration Schema and Validation¶

Defines typed models for each configuration category:
Processing pipeline settings
AI classifier parameters
Database connections
Notification services
Enforces required fields, allowed ranges, and cross-field constraints.
Provides structured error messages for invalid inputs.

Typical behaviors:

Reject partial or malformed payloads with precise field-level errors.
Normalize values (e.g., trimming strings, coercing booleans).
Validate secrets presence when enabled features require them.

Section sources

config.py

Hierarchical Configuration Resolution¶

Resolution order:

Built-in defaults
Environment variables (override defaults)
File-based configuration (overrides env and defaults)

Rules:

Deep merge semantics for nested objects.
Environment variables use a naming convention mapping to nested keys.
File-based configuration supports incremental patches.

Dynamic behavior:

Hot reload triggers re-validation and applies only valid diffs.
Rollback on validation failure preserves previous state.

Section sources

config.py

API Endpoints¶

Read Configuration¶

Endpoint: GET /api/config
Behavior: Returns the effective configuration after applying hierarchy.
Response: Full configuration object conforming to schema.

Use cases:

Initial dashboard load
Pre-flight checks before updates

Section sources

config.py

Update Configuration (Single Key or Section)¶

Endpoint: PATCH /api/config
Behavior: Applies a patch to one or more keys/sections.
Validation: Runs schema validation against patched state.
Persistence: Persists changes atomically; rolls back on failure.
Response: Updated effective configuration.

Notes:

Supports nested key paths.
Validates only changed fields but ensures global consistency.

Section sources

config.py

Bulk Update Configuration¶

Endpoint: PUT /api/config
Behavior: Replaces specified sections or entire configuration tree.
Validation: Full schema validation on merged result.
Persistence: Atomic write with snapshotting for rollback.
Response: Updated effective configuration.

Security:

Requires elevated privileges.
Audit logging enabled.

Section sources

config.py

Validate Configuration¶

Endpoint: POST /api/config/validate
Behavior: Validates a provided payload without persisting.
Response: Validation result with detailed errors if any.

Use cases:

Dry-run before applying changes
External tooling integration

Section sources

config.py

Backup Configuration¶

Endpoint: POST /api/config/backup
Behavior: Creates a snapshot of current effective configuration.
Response: Snapshot metadata and location reference.

Operational notes:

Backups are versioned and timestamped.
Can be used for disaster recovery.

Section sources

config.py

Restore Configuration¶

Endpoint: POST /api/config/restore
Behavior: Restores configuration from a previously created snapshot.
Validation: Post-restore validation ensures integrity.
Response: Confirmation with restored state summary.

Safety:

Requires confirmation parameter.
Logs restoration events.

Section sources

config.py

Configuration Categories¶

Processing Pipeline Settings
Includes queue sizes, concurrency limits, retry policies, and timeouts.
Validated ranges and non-negative constraints.
AI Classifier Parameters
Model selection, thresholds, confidence cutoffs, and feature toggles.
Cross-field validation (e.g., threshold within allowed range).
Database Connections
Connection strings, pool sizes, timeouts, and SSL flags.
Secret masking in logs and responses.
Notification Services
Providers, channels, templates, and rate limits.
Optional secret fields for credentials.

Each category is modeled in the schema layer and enforced during updates and validations.

Section sources

config.py

Dynamic Configuration Updates¶

The dashboard service calls PATCH/PUT endpoints to apply changes.
On success, the UI refreshes configuration views without full page reload.
Errors surface as actionable messages aligned with schema validation.

Integration points:

UI service encapsulates endpoint calls and error normalization.

Section sources

Configuration Migration Procedures¶

Versioned migrations ensure compatibility across deployments.
Migration scripts adjust legacy keys to new schema structures.
Post-migration validation guarantees a clean effective configuration.

Recommended flow:

Run migration script
Validate configuration
Apply minimal patch if needed
Confirm successful upgrade

Section sources

Security Considerations¶

Sensitive Data Handling:

Secrets are masked in logs and API responses.
Encryption at rest for stored configuration files.
Strict input validation prevents injection and type confusion.

Access Control:

Read-only endpoints may be accessible to lower-privilege roles.
Write endpoints require admin or operator role.
Audit logging captures who changed what and when.

Environment Isolation:

Environment variables can override specific keys securely.
Prefer passing secrets via environment rather than files.

Section sources

Dependency Analysis¶

Configuration components interact through clear boundaries:

Routes depend on loader and persistence abstractions.
Loader depends on schema definitions for validation.
UI service depends on routes for client interactions.

classDiagram

class ConfigSchemas {

+models_and_validators

}

class ConfigLoader {

+load()

+validate_and_apply(patch)

}

class ConfigRoutes {

+GET /api/config

+PATCH /api/config

+PUT /api/config

+POST /api/config/validate

+POST /api/config/backup

+POST /api/config/restore

}

class UIService {

+fetch_config()

+patch_config(patch)

+bulk_update(data)

+validate(payload)

+backup()

+restore(snapshot_id)

}

ConfigRoutes --> ConfigLoader : "uses"

ConfigLoader --> ConfigSchemas : "validates"

UIService --> ConfigRoutes : "calls"

Diagram sources

Section sources

Performance Considerations¶

Use PATCH for targeted updates to minimize serialization overhead.
Cache effective configuration in memory with short TTL for read-heavy workloads.
Defer heavy validation to background jobs for large bulk updates.
Avoid frequent hot reloads under high load; batch changes when possible.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Common issues and resolutions:

Validation failures: Inspect field-level error messages returned by POST /api/config/validate.
Permission denied on writes: Verify user role and access control settings.
Secret not found: Ensure environment variables or secure store entries exist.
Migration conflicts: Run validation post-migration and apply corrective patches.

Operational tips:

Use backup before major changes.
Keep audit logs for change tracking.
Monitor configuration drift between environments.

Section sources

config.py

Conclusion¶

Nexo’s configuration management system provides a robust, validated, and secure interface for managing application settings. Its layered architecture ensures clarity, maintainability, and safety, while supporting dynamic updates and operational workflows like backup and restore. By following the documented endpoints and best practices, operators can confidently manage configuration across development, staging, and production environments.

[No sources needed since this section summarizes without analyzing specific files]

Appendices¶

Example Scenarios¶

Reading Current Settings
Call GET /api/config to retrieve effective configuration.
Use the response to pre-fill forms or perform readiness checks.
Updating a Single Setting
Send PATCH /api/config with a small patch object targeting a nested key.
Validate first using POST /api/config/validate if unsure.
Bulk Update
Send PUT /api/config with a complete replacement payload for selected sections.
Expect full validation and atomic persistence.
Backup and Restore
Create a backup via POST /api/config/backup.
Restore later using POST /api/config/restore with the snapshot identifier.
Dynamic Update from Dashboard
Use the UI service to call PATCH/PUT endpoints and refresh views on success.

[No sources needed since this section provides conceptual examples]