Configuration Management¶

Referenced Files in This Document - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/service/routes/config.py - apps/service/routes/users.py - apps/shared/schemas/config.py - apps/shared/schemas/user.py - apps/shared/config.py - apps/shared/models/user.py - apps/ui/dashboard/services/config_svc.py - apps/ui/dashboard/services/users_svc.py

Introduction¶

This document explains the configuration management interface, including the settings panel, validation rules, default values, environment-specific configurations, import/export and versioning for backups, rollback capabilities, user administration (creation, roles, permissions, password policies), form validation, error handling, and real-time updates without service restarts. It also provides guidance on extending configuration options, implementing custom validation, and integrating with external authentication providers.

Project Structure¶

The configuration management spans frontend pages, backend routes, shared schemas, models, and UI services: - Frontend pages: Settings and Users - Backend routes: Configuration and User endpoints - Shared schemas: Pydantic models for request/response validation - Shared config: Centralized configuration loading and defaults - Models: Persistent entities (e.g., users) - UI services: Client-side API clients for configuration and users

graph TB
subgraph "Frontend"
CFG_PAGE["Config.tsx"]
USR_PAGE["Usuarios.tsx"]
CFG_SVC["config_svc.py"]
USR_SVC["users_svc.py"]
end
subgraph "Backend"
CFG_ROUTE["routes/config.py"]
USR_ROUTE["routes/users.py"]
SHARED_CFG["shared/config.py"]
SCHEMA_CFG["shared/schemas/config.py"]
SCHEMA_USR["shared/schemas/user.py"]
MODEL_USR["shared/models/user.py"]
end
CFG_PAGE --> CFG_SVC
USR_PAGE --> USR_SVC
CFG_SVC --> CFG_ROUTE
USR_SVC --> USR_ROUTE
CFG_ROUTE --> SCHEMA_CFG
USR_ROUTE --> SCHEMA_USR
USR_ROUTE --> MODEL_USR
CFG_ROUTE --> SHARED_CFG

Diagram sources - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/ui/dashboard/services/config_svc.py - apps/ui/dashboard/services/users_svc.py - apps/service/routes/config.py - apps/service/routes/users.py - apps/shared/config.py - apps/shared/schemas/config.py - apps/shared/schemas/user.py - apps/shared/models/user.py

Section sources - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/ui/dashboard/services/config_svc.py - apps/ui/dashboard/services/users_svc.py - apps/service/routes/config.py - apps/service/routes/users.py - apps/shared/config.py - apps/shared/schemas/config.py - apps/shared/schemas/user.py - apps/shared/models/user.py

Core Components¶

Settings Panel (frontend): Renders configuration fields, applies client-side validation, and persists changes via API calls.
Configuration Routes (backend): Expose endpoints to read, update, validate, export/import, and manage versions of configuration.
Shared Schemas: Define validated data structures for requests/responses and enforce constraints.
Shared Config: Loads defaults, merges environment variables, and exposes a unified configuration object.
User Administration: Endpoints and forms for creating users, assigning roles, managing permissions, and enforcing password policies.
UI Services: Encapsulate HTTP interactions for configuration and users from the dashboard.

Key responsibilities: - Validation at multiple layers (client and server) - Real-time updates through immediate persistence and optional live refresh - Import/export for backups and versioned rollbacks - Role-based access control for sensitive operations

Section sources - apps/dashboard/src/pages/Config.tsx - apps/service/routes/config.py - apps/shared/schemas/config.py - apps/shared/config.py - apps/dashboard/src/pages/Usuarios.tsx - apps/service/routes/users.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/ui/dashboard/services/config_svc.py - apps/ui/dashboard/services/users_svc.py

Architecture Overview¶

The configuration flow involves the dashboard page calling UI services, which invoke backend routes. The backend validates payloads using shared schemas, reads/writes configuration via the shared config module, and returns structured responses. User administration follows a similar pattern with additional role and permission checks.

sequenceDiagram
participant FE as "Config Page"
participant SVC as "config_svc.py"
participant API as "routes/config.py"
participant SC as "schemas/config.py"
participant CFG as "shared/config.py"
FE->>SVC : "loadConfig()"
SVC->>API : "GET /api/config"
API->>CFG : "read merged config"
CFG-->>API : "configuration object"
API-->>SVC : "validated response"
SVC-->>FE : "settings state"
FE->>SVC : "saveConfig(partial)"
SVC->>API : "PATCH /api/config"
API->>SC : "validate payload"
SC-->>API : "valid or errors"
API->>CFG : "update keys"
CFG-->>API : "updated config"
API-->>SVC : "success + updated values"
SVC-->>FE : "persisted state"

Diagram sources - apps/dashboard/src/pages/Config.tsx - apps/ui/dashboard/services/config_svc.py - apps/service/routes/config.py - apps/shared/schemas/config.py - apps/shared/config.py

Detailed Component Analysis¶

Settings Panel (Configuration)¶

Responsibilities: - Display current configuration grouped by sections - Apply client-side validation rules and show inline errors - Persist changes immediately via PATCH endpoint - Support import/export JSON for backups - Show version history and allow rollback to previous versions - Reflect environment overrides and mark overridden fields

Validation rules and defaults: - Server-side validation is enforced by shared schemas; client-side mirrors common constraints (required fields, ranges, formats). - Defaults are provided by the shared configuration loader; environment variables can override specific keys.

Real-time updates: - On successful save, the UI updates only changed fields and may refresh dependent sections without restarting the service.

Import/Export and Versioning: - Export: serializes current configuration to JSON for backup. - Import: validates incoming JSON against schema, creates a new version snapshot, and applies it. - Rollback: selects a prior version snapshot and restores it atomically.

flowchart TD
Start(["Open Settings"]) --> Load["Load current config"]
Load --> Edit["Edit fields<br/>Client validation"]
Edit --> Save{"Save?"}
Save --> |Yes| Patch["PATCH /api/config"]
Patch --> Validate["Server validates via schema"]
Validate --> Update["Update shared config"]
Update --> Success["Return updated values"]
Success --> Refresh["UI reflects changes"]
Save --> |No| Cancel["Discard changes"]
Cancel --> End(["Exit"])
Success --> End

Diagram sources - apps/dashboard/src/pages/Config.tsx - apps/ui/dashboard/services/config_svc.py - apps/service/routes/config.py - apps/shared/schemas/config.py - apps/shared/config.py

Section sources - apps/dashboard/src/pages/Config.tsx - apps/ui/dashboard/services/config_svc.py - apps/service/routes/config.py - apps/shared/schemas/config.py - apps/shared/config.py

User Administration¶

Features: - Create, list, update, and delete users - Assign roles and manage permissions per role - Enforce password policies during creation and updates - Securely handle credentials and session tokens

User model and schema: - User entity includes identity, role, permissions, and password metadata. - Request/response schemas enforce required fields, format constraints, and policy rules.

Role and permission management: - Roles define sets of permissions. - Admin-only endpoints protect sensitive operations.

Password policies: - Minimum length, complexity requirements, and hashing strategy are enforced server-side.

classDiagram
class UserModel {
+id
+username
+role
+permissions
+password_hash
}
class UserSchema {
+create(data)
+update(data)
+list()
}
class UsersRoute {
+create_user()
+update_user()
+delete_user()
+assign_role()
}
UserModel <.. UserSchema : "validated by"
UsersRoute --> UserSchema : "uses"
UsersRoute --> UserModel : "persists"

Diagram sources - apps/shared/models/user.py - apps/shared/schemas/user.py - apps/service/routes/users.py

Section sources - apps/dashboard/src/pages/Usuarios.tsx - apps/ui/dashboard/services/users_svc.py - apps/service/routes/users.py - apps/shared/schemas/user.py - apps/shared/models/user.py

Environment-Specific Configuration¶

Defaults are defined centrally and applied when no explicit value is set.
Environment variables can override specific keys, enabling different behavior across development, staging, and production.
The configuration loader merges defaults, file-based settings, and environment variables into a single source of truth.

Operational notes: - Changes to environment variables require reloading the configuration layer; some subsystems may need restarts depending on their initialization timing. - Prefer runtime-updatable keys for hot-reload scenarios.

Section sources - apps/shared/config.py

Import/Export and Versioning¶

Export: Serializes the current configuration snapshot to JSON for backup.
Import: Validates the uploaded JSON against the configuration schema, records a new version, and applies it.
Versioning: Each import or significant update creates a versioned snapshot.
Rollback: Selecting a prior version restores that snapshot atomically.

Error handling: - Invalid JSON or schema violations return detailed errors indicating field-level issues. - Rollback failures are logged and surfaced to the user with actionable messages.

Section sources - apps/service/routes/config.py - apps/shared/schemas/config.py

Form Validation and Error Handling¶

Client-side validation provides immediate feedback before submission.
Server-side validation enforces business rules and prevents invalid states.
Errors are normalized and returned consistently, allowing the UI to display precise messages.

Best practices: - Mirror critical constraints on both client and server. - Use descriptive error codes and messages for better troubleshooting.

Section sources - apps/dashboard/src/pages/Config.tsx - apps/service/routes/config.py - apps/shared/schemas/config.py

Real-Time Updates Without Restarts¶

Hot-reloadable configuration keys are persisted immediately and consumed by components that support dynamic updates.
UI reflects changes instantly after successful saves.
For subsystems that initialize once at startup, document which keys require restarts.

Section sources - apps/dashboard/src/pages/Config.tsx - apps/service/routes/config.py - apps/shared/config.py

Dependency Analysis¶

The following diagram shows how components depend on each other for configuration and user management.

graph LR
CFG_PAGE["Config.tsx"] --> CFG_SVC["config_svc.py"]
USR_PAGE["Usuarios.tsx"] --> USR_SVC["users_svc.py"]
CFG_SVC --> CFG_ROUTE["routes/config.py"]
USR_SVC --> USR_ROUTE["routes/users.py"]
CFG_ROUTE --> SCHEMA_CFG["schemas/config.py"]
USR_ROUTE --> SCHEMA_USR["schemas/user.py"]
USR_ROUTE --> MODEL_USR["models/user.py"]
CFG_ROUTE --> SHARED_CFG["shared/config.py"]

Diagram sources - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/ui/dashboard/services/config_svc.py - apps/ui/dashboard/services/users_svc.py - apps/service/routes/config.py - apps/service/routes/users.py - apps/shared/schemas/config.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/shared/config.py

Section sources - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Usuarios.tsx - apps/ui/dashboard/services/config_svc.py - apps/ui/dashboard/services/users_svc.py - apps/service/routes/config.py - apps/service/routes/users.py - apps/shared/schemas/config.py - apps/shared/schemas/user.py - apps/shared/models/user.py - apps/shared/config.py

Performance Considerations¶

Minimize payload size by sending only changed fields (PATCH).
Cache frequently accessed configuration on the client side and invalidate on updates.
Avoid heavy computations during configuration load; defer to background tasks if needed.
Use efficient serialization for import/export and consider compression for large backups.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Common issues and resolutions: - Validation errors: Check field constraints in shared schemas and ensure client-side rules match server expectations. - Import failures: Verify JSON structure matches expected schema; inspect error details for exact field violations. - Rollback problems: Confirm the target version exists and is intact; review logs for transactional failures. - Environment overrides: Ensure environment variable names align with supported keys; verify precedence order. - Permission denied: Confirm the current user’s role has sufficient permissions for the requested operation.

Section sources - apps/service/routes/config.py - apps/service/routes/users.py - apps/shared/schemas/config.py - apps/shared/schemas/user.py

Conclusion¶

The configuration management interface provides a robust, validated, and extensible system for managing application settings and user administration. With clear separation between frontend, backend, schemas, and shared configuration, it supports safe updates, versioned backups, and streamlined rollbacks. Following the extension guidelines ensures maintainability and consistency as new features are added.

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

Appendices¶

Extending Configuration Options¶

Steps to add a new configuration option: - Define the key and its type/constraints in the shared configuration loader. - Add corresponding fields and validation rules in the shared configuration schema. - Expose endpoints in the configuration route to read/update the new key. - Update the settings panel to render and persist the new field. - If the feature requires a restart, document it clearly.

Section sources - apps/shared/config.py - apps/shared/schemas/config.py - apps/service/routes/config.py - apps/dashboard/src/pages/Config.tsx

Implementing Custom Validation Rules¶

Approach: - Add custom validators in the shared configuration schema to enforce domain-specific constraints. - Mirror essential validations on the client side for better UX. - Return structured error messages indicating the failing rule and suggested fixes.

Section sources - apps/shared/schemas/config.py - apps/service/routes/config.py - apps/dashboard/src/pages/Config.tsx

Integrating External Authentication Providers¶

Guidance: - Extend the user schema and routes to support provider-specific attributes (e.g., provider ID, token metadata). - Implement secure credential handling and token exchange flows. - Map external roles to internal roles and permissions. - Provide admin controls to configure provider credentials and enable/disable providers.

Section sources - apps/shared/schemas/user.py - apps/service/routes/users.py - apps/shared/models/user.py