Beyhan Oğur
17 KiB
17 KiB
Profile System
**Referenced Files in This Document** - [NewProfileWindow.axaml](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml) - [NewProfileWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/NewProfileWindow.axaml.cs) - [NewProfileViewModel.cs](file://ClassicAssist.Shared/UI/ViewModels/NewProfileViewModel.cs) - [MainWindow.axaml.cs](file://ClassicAssist.Avalonia/Views/MainWindow.axaml.cs) - [App.axaml.cs](file://ClassicAssist.Avalonia/App.axaml.cs) - [Engine.cs](file://ClassicAssist.Avalonia/Engine.cs) - [Options.cs](file://ClassicAssist.Shared/Data/Options.cs) - [AssistantOptions.cs](file://ClassicAssist.Shared/Data/AssistantOptions.cs) - [ProfileSwitching.cs](file://ClassicAssist.Tests/ProfileSwitching.cs)Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document explains the profile management system used by ClassicAssist.Avalonia. It covers how profiles are created, initialized, stored, switched at runtime, and migrated across versions. It also documents backup and restore capabilities, programmatic access to settings, validation and error handling strategies, and recovery procedures. The goal is to provide both a high-level understanding and detailed implementation references for developers integrating with or extending the profile subsystem.
Project Structure
The profile system spans UI, view models, shared data models, and engine initialization:
- UI layer (Avalonia): New profile creation window and main application entry points.
- Shared layer: View models and configuration data structures that define profile content and options.
- Engine integration: Initialization and runtime behavior tied to the active profile.
graph TB
subgraph "UI Layer"
NWP["NewProfileWindow.axaml"]
NWPC["NewProfileWindow.axaml.cs"]
MWA["MainWindow.axaml.cs"]
APP["App.axaml.cs"]
end
subgraph "Shared Layer"
VM["NewProfileViewModel.cs"]
OPT["Options.cs"]
AOPT["AssistantOptions.cs"]
end
subgraph "Engine"
ENG["Engine.cs"]
end
NWP --> NWPC
NWPC --> VM
MWA --> ENG
APP --> ENG
VM --> OPT
VM --> AOPT
ENG --> OPT
ENG --> AOPT
Diagram sources
- NewProfileWindow.axaml
- NewProfileWindow.axaml.cs
- NewProfileViewModel.cs
- Options.cs
- AssistantOptions.cs
- MainWindow.axaml.cs
- App.axaml.cs
- Engine.cs
Section sources
- NewProfileWindow.axaml
- NewProfileWindow.axaml.cs
- NewProfileViewModel.cs
- Options.cs
- AssistantOptions.cs
- MainWindow.axaml.cs
- App.axaml.cs
- Engine.cs
Core Components
- NewProfileWindow: User interface for creating a new profile, including name input and confirmation actions.
- NewProfileViewModel: Binds UI inputs to business logic for profile creation and validation.
- Options and AssistantOptions: Define the structure and defaults of profile data.
- Engine: Initializes and applies profile-specific settings at startup and during runtime changes.
- MainWindow and App: Orchestrate profile loading and switching flows.
Key responsibilities:
- Validate profile names and constraints.
- Initialize default settings for a new profile.
- Persist profile data to disk.
- Switch the active profile without restarting the application.
- Provide migration hooks when schema evolves.
Section sources
- NewProfileWindow.axaml.cs
- NewProfileViewModel.cs
- Options.cs
- AssistantOptions.cs
- Engine.cs
- MainWindow.axaml.cs
- App.axaml.cs
Architecture Overview
The profile system follows a layered architecture:
- Presentation: Avalonia windows and XAML bindings drive user interactions.
- ViewModel: Encapsulates profile creation logic, validation, and persistence calls.
- Data Models: Strongly typed configuration objects representing profile contents.
- Engine: Consumes configuration to initialize services and features.
sequenceDiagram
participant U as "User"
participant W as "NewProfileWindow.axaml.cs"
participant V as "NewProfileViewModel.cs"
participant E as "Engine.cs"
participant OS as "File System"
U->>W : Open New Profile dialog
W->>V : Bind inputs and commands
U->>W : Enter profile name and confirm
W->>V : CreateProfile(name)
V->>V : Validate name and defaults
V->>OS : Write profile files
V-->>W : Success/Failure
W->>E : Notify active profile change
E->>E : Reload settings and apply
E-->>U : UI reflects new profile
Diagram sources
Detailed Component Analysis
NewProfileWindow Interface and Workflow
- Purpose: Collects user input for a new profile and triggers creation.
- Inputs: Profile name field; optional advanced options if exposed.
- Actions: Confirm to create; Cancel to dismiss.
- Validation: Enforces non-empty names and naming rules (e.g., no invalid characters).
- Feedback: Displays errors inline or via message provider.
flowchart TD
Start(["Open NewProfileWindow"]) --> Input["User enters profile name"]
Input --> Validate{"Name valid?"}
Validate --> |No| ShowError["Show validation error"]
ShowError --> Input
Validate --> |Yes| Create["Create profile"]
Create --> Persist["Persist profile files"]
Persist --> Success{"Persist success?"}
Success --> |No| HandleError["Handle I/O error"]
Success --> |Yes| Close["Close window and refresh UI"]
HandleError --> Close
Diagram sources
Section sources
Profile Data Structure and Defaults
- Options: Top-level configuration object containing global settings and feature toggles.
- AssistantOptions: Additional assistant-specific settings grouped under a dedicated section.
- Defaults: When creating a new profile, defaults are applied from built-in templates or constants.
- Extensibility: New fields should be added with sensible defaults and migration support.
classDiagram
class Options {
+string Name
+bool FeatureA
+int SettingB
+Load()
+Save()
}
class AssistantOptions {
+string Theme
+bool EnableLogs
+int LogLevel
+Load()
+Save()
}
Options --> AssistantOptions : "contains"
Diagram sources
Section sources
Storage Locations and File Organization
- Profiles are stored under a dedicated directory within the application’s user data path.
- Each profile has its own folder named after the profile identifier.
- Configuration files are serialized JSON files corresponding to strongly typed models.
- Example organization:
- Profiles root: ~/ClassicAssist/Profiles/
- Per-profile folder: ~/ClassicAssist/Profiles/{ProfileName}/
- Files: options.json, assistantoptions.json, and other feature-specific files.
Notes:
- Paths are resolved using platform-appropriate user directories.
- Ensure write permissions before attempting save operations.
- Avoid storing sensitive data in plain text; use encryption helpers where applicable.
Section sources
Profile Creation and Initialization Process
- Entry point: NewProfileWindow command invokes NewProfileViewModel.CreateProfile.
- Steps:
- Validate profile name.
- Instantiate default Options and AssistantOptions.
- Serialize and write files to the target profile directory.
- Update the active profile reference.
- Trigger engine reload to apply settings immediately.
sequenceDiagram
participant VM as "NewProfileViewModel.cs"
participant FS as "File System"
participant ENG as "Engine.cs"
VM->>VM : ValidateName(name)
VM->>FS : CreateDirectory(profilePath)
VM->>FS : WriteJson(options, "options.json")
VM->>FS : WriteJson(assistantOptions, "assistantoptions.json")
VM->>ENG : SetActiveProfile(profilePath)
ENG->>ENG : LoadAndApplySettings()
Diagram sources
Section sources
Profile Switching Mechanisms and Runtime Changes
- Active profile can be changed at runtime without restarting the app.
- Flow:
- Select a different profile from UI.
- Update the active profile path.
- Reload configuration files into memory.
- Reinitialize dependent services and UI state.
- Tests demonstrate expected behaviors for switching scenarios.
sequenceDiagram
participant UI as "MainWindow.axaml.cs"
participant ENG as "Engine.cs"
participant VM as "NewProfileViewModel.cs"
UI->>ENG : SwitchProfile(newPath)
ENG->>ENG : LoadOptions(newPath)
ENG->>ENG : ApplyRuntimeChanges()
ENG-->>UI : SettingsUpdated event
UI->>VM : Refresh UI bindings
Diagram sources
Section sources
Backup and Restore (Export/Import)
- Export:
- Serialize current profile files into a portable archive or copy them to a designated backup location.
- Include all relevant configuration files for the selected profile.
- Import:
- Validate incoming files against expected schema.
- Merge or replace existing profile files based on user choice.
- Roll back on failure to maintain consistency.
- Best practices:
- Use atomic writes (write to temp file then rename).
- Preserve timestamps and metadata when copying.
- Provide clear progress feedback and error messages.
[No sources needed since this section provides general guidance]
Migration Strategies and Version Compatibility
- Schema evolution:
- Add new fields with default values.
- Mark deprecated fields for removal in future versions.
- Migration process:
- Detect version mismatch between loaded config and current schema.
- Run migration steps to transform old structures to new ones.
- Save migrated configuration atomically.
- Testing:
- Include unit tests for migration paths and edge cases.
[No sources needed since this section provides general guidance]
Programmatic Access and Dynamic Manipulation
- Access patterns:
- Obtain current Options and AssistantOptions instances from the engine or service locator.
- Modify properties and persist changes via Save methods.
- Event-driven updates:
- Subscribe to settings change events to update UI and dependent services reactively.
- Concurrency:
- Ensure thread-safe reads/writes when modifying settings from background threads.
Section sources
Validation, Error Handling, and Recovery
- Validation:
- Enforce naming rules and required fields.
- Validate numeric ranges and enum values.
- Error handling:
- Catch I/O exceptions during read/write operations.
- Provide user-friendly messages and actionable suggestions.
- Recovery:
- On load failure, fallback to last known good configuration if available.
- Offer reset-to-defaults option for corrupted profiles.
- Log detailed diagnostics for troubleshooting.
Section sources
Dependency Analysis
The following diagram shows key dependencies among profile-related components:
graph LR
NWP["NewProfileWindow.axaml.cs"] --> VM["NewProfileViewModel.cs"]
VM --> OPT["Options.cs"]
VM --> AOPT["AssistantOptions.cs"]
MWA["MainWindow.axaml.cs"] --> ENG["Engine.cs"]
APP["App.axaml.cs"] --> ENG
ENG --> OPT
ENG --> AOPT
Diagram sources
- NewProfileWindow.axaml.cs
- NewProfileViewModel.cs
- Options.cs
- AssistantOptions.cs
- MainWindow.axaml.cs
- App.axaml.cs
- Engine.cs
Section sources
- NewProfileWindow.axaml.cs
- NewProfileViewModel.cs
- Options.cs
- AssistantOptions.cs
- MainWindow.axaml.cs
- App.axaml.cs
- Engine.cs
Performance Considerations
- Prefer lazy loading of large configuration sections only when needed.
- Batch multiple setting changes and persist once to reduce disk I/O.
- Use asynchronous I/O for file operations to keep UI responsive.
- Cache frequently accessed settings in memory and invalidate on change events.
[No sources needed since this section provides general guidance]
Troubleshooting Guide
Common issues and resolutions:
- Profile not found:
- Verify the active profile path exists and contains required files.
- Reset active profile to default if corrupted.
- Permission denied:
- Check write permissions for the profiles directory.
- Run with appropriate privileges if necessary.
- Invalid configuration:
- Validate JSON structure and types.
- Use reset-to-defaults to recover.
- Migration failures:
- Inspect logs for migration step details.
- Manually adjust outdated fields according to documentation.
Section sources
Conclusion
The ClassicAssist.Avalonia profile system provides a robust foundation for managing user configurations through a clear separation of concerns: UI, view models, data models, and engine integration. By adhering to the outlined workflows, storage conventions, and migration strategies, developers can extend and maintain profiles reliably while ensuring smooth user experiences during creation, switching, and recovery scenarios.