AI Icon Suggestion
Relevant source files
The following files were used as context for generating this wiki page:
- Packages/Interfaces/Sources/Interfaces/Services/IconSuggestionService.swift
- Packages/Services/Sources/Services/IconSuggestion/IconSuggestionServiceImpl.swift
- Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsViewModel.swift
- Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsView.swift
- Features/CategoriesFeature/Tests/CategoriesFeatureTests/Views/CategoryForm/AISuggestedIconsViewModelTests.swift
- Packages/Mocks/Sources/Mocks/Services/IconSuggestionServiceMock.swift
The AI Icon Suggestion system provides an automated way for users to discover relevant icons (both SF Symbols and emojis) when creating or editing categories within the Trackurr application. By analyzing the name of a category, the system leverages on-device AI to generate a curated list of visual representations, enhancing the user experience through intelligent automation.
The feature is designed as a modular service with a reactive UI component that updates suggestions in real-time as the user types, using debouncing and validation to ensure efficiency and relevance.
Sources: Packages/Interfaces/Sources/Interfaces/Services/IconSuggestionService.swift, Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsView.swift
Architecture and Data Flow
The architecture follows a clear separation of concerns, moving from the UI layer down to the underlying AI service implementation.
Service Layer and Interfaces
The system is anchored by the IconSuggestionService protocol, which defines the requirements for any implementation providing icon suggestions. It requires a property to check feature availability and an asynchronous function to fetch results.
The concrete implementation, IconSuggestionServiceImpl, utilizes Apple's FoundationModels framework. It constructs a specific prompt for a LanguageModelSession to suggest up to five SF Symbols and five emojis based on the provided category name.
Sources: Packages/Interfaces/Sources/Interfaces/Services/IconSuggestionService.swift:16-25, Packages/Services/Sources/Services/IconSuggestion/IconSuggestionServiceImpl.swift:23-49
Component Interaction
The following diagram illustrates the interaction between the UI, the View Model, and the underlying Service.
The diagram shows the asynchronous flow from user input to the final display of AI-generated icons, including the crucial debouncing and filtering steps.
Sources: Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsViewModel.swift:41-76, Packages/Services/Sources/Services/IconSuggestion/IconSuggestionServiceImpl.swift:30-46
Logic and Implementation Details
View Model Orchestration
The AISuggestedIconsViewModel manages the state and business logic for the suggestion feature. It handles the following critical tasks:
- Debouncing: Requests are delayed by 500ms to prevent excessive API calls while the user is actively typing. Previous tasks are cancelled if a new character is entered.
- Input Validation: Suggestions are only triggered if the trimmed category name is at least 3 characters long.
- Symbol Validation: Before displaying an SF Symbol, the View Model verifies its existence on the current device using
UIImage(systemName:). - Error Handling: If the service fails or throws an error, the suggested icons list is cleared to prevent displaying stale or incorrect data.
Sources: Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsViewModel.swift:32-76, Features/CategoriesFeature/Tests/CategoriesFeatureTests/Views/CategoryForm/AISuggestedIconsViewModelTests.swift:35-64
Data Structures
The data is passed between layers using specific structures:
| Structure | Description | Fields |
|---|---|---|
IconSuggestionResult | The output of the suggestion service. | symbols: [String], emojis: [String] |
IconSuggestions | The internal AI-generable structure used for LLM response mapping. | sfSymbols: [String], emojis: [String] |
Icon | The domain model representing a choice (Symbol or Emoji). | .symbol(String), .emoji(String) |
Sources: Packages/Interfaces/Sources/Interfaces/Services/IconSuggestionService.swift:4-13, Packages/Services/Sources/Services/IconSuggestion/IconSuggestionServiceImpl.swift:9-16
UI Integration
The AISuggestedIconsView is a SwiftUI component that integrates into category forms. It monitors changes to the categoryName binding and triggers the view model's logic.
- Loading State: While suggestions are being fetched, it displays a
ProgressViewwith a "Getting AI suggestions..." message. - Grid Display: Successful results are displayed in a 6-column flexible grid using
IconButtonView. - Availability: The view only renders its content if
viewModel.isFeatureAvailableis true, which typically depends on device OS version and hardware capabilities.
Sources: Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsView.swift:15-50, Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsViewModel.swift:15-18
Class Relationship Diagram
This diagram represents the structural dependency between the UI components and the service layer.
Sources: Packages/Interfaces/Sources/Interfaces/Services/IconSuggestionService.swift, Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsViewModel.swift
Requirements and Constraints
| Constraint | Value | Description |
|---|---|---|
| Minimum Name Length | 3 characters | Logic ignores names shorter than 3 characters after trimming. |
| Debounce Duration | 500ms | Default time to wait after typing stops before calling the service. |
| OS Requirement | iOS 26+ | The IconSuggestionServiceImpl is gated by @available(iOS 26, *). |
| Max Suggestions | 5 Symbols / 5 Emojis | The AI prompt explicitly asks for up to 5 of each. |
Sources: Features/CategoriesFeature/Sources/CategoriesFeature/Views/AISuggestedIcons/AISuggestedIconsViewModel.swift:34-44, Packages/Services/Sources/Services/IconSuggestion/IconSuggestionServiceImpl.swift:34-37
Summary
The AI Icon Suggestion module is a sophisticated utility that bridges Apple's on-device foundation models with the Trackurr user interface. By implementing a robust service-based architecture with proper debouncing and validation logic, the system provides a seamless and responsive experience that assists users in visually organizing their financial data.