Technical Design TDD-0001 — Icon Management System¶

1. Summary¶

This technical design document outlines the implementation of a comprehensive icon management system within the loryth-cms service. The system will enable users to upload, search, and reference icons, supporting individual icon uploads and icon package imports. It will handle multiple image formats and provide flexible searching capabilities through names and aliases.

2. Context and Problem Statement¶

The current icon system follows a client-driven approach with significant limitations. Icons are simply persisted as string identifiers on the backend, while the client application is responsible for maintaining a comprehensive registry of icons, their visual representations, and metadata.

The existing implementation includes:

• Icons stored only as string references in the backend data models
• A static, code-based icon registry in the frontend that defines available icons with names, aliases, and categories
• Frontend utilities for searching and grouping these predefined icons
• No capability for users to add custom icons or manage icon collections dynamically
• Limited extensibility as adding new icons requires code changes and redeployment

This client-driven approach creates several challenges: it limits the system's flexibility, requires developer intervention for any icon updates, prevents users from contributing their own icons, and makes it impossible to manage different icon sets for different purposes.

This TDD aims to transform the system into a comprehensive server-side icon management solution that maintains the current frontend capabilities while adding dynamic icon upload, storage, and management features.

2.1 Goals¶

Functional Requirements¶

1. Users should be able to upload icons individually
2. Users should be able to upload icons as an icon package
3. Users should be able to search icons by name or alias
4. Icons must be referenced by a stable identifier (name), so that icon image changes don't affect references
5. Support for jpg, png, svg, webp, and gif image formats
6. Support for colored SVG icons that can change color

Non-functional Requirements¶

• Performance: Icon search operations should respond within 200ms
• Scalability: The system should handle icon libraries with up to 10,000 icons
• Security: Proper validation of uploaded image files to prevent security vulnerabilities
• Accessibility: Icons should support accessibility requirements including alt text
• Usability: Intuitive interface for icon management and search

2.2 Out of Scope¶

Not defined.

2.3 Assumptions and Constraints¶

• File storage system (S3, local filesystem, etc.)
• Image processing library for format validation and manipulation
• SVG parsing and manipulation library
• Zip file handling library for icon packages

2.4 Open Questions¶

• Should we support icon versioning to track changes over time?
• How should we handle migration from the current hardcoded icon system?
• Should we implement an approval workflow for user-uploaded icons?
• What are the specific performance requirements for icon rendering?

3. Design Overview¶

The icon management system will consist of the following components:

graph TD
    User(User) --> UploadService[Icon Upload Service]
    User --> SearchService[Icon Search Service]
    UploadService --> ValidationService[Icon Validation Service]
    ValidationService --> StorageService[Icon Storage Service]
    ValidationService --> MetadataService[Icon Metadata Service]
    SearchService --> MetadataService
    MetadataService --> Database[(Icon Database)]
    StorageService --> FileStorage[(File Storage)]
    API[Icon API] --> UploadService
    API --> SearchService
    WebClient[Web Client] --> API

3.1 Key Components¶

3.2 Architecture¶

Data Model¶

erDiagram
    IconPackage ||--o{ Icon: contains
    Icon ||--|| IconMetadata: has
    Icon ||--o{ IconAlias: has
    Icon ||--o{ IconVariant: has

    IconPackage {
        uuid id PK
        string name
        string description
        timestamp created_at
        timestamp updated_at
    }

    Icon {
        uuid id PK
        uuid package_id FK
        string name
        string file_path
        string format
        bool supports_color
        timestamp created_at
        timestamp updated_at
    }

    IconMetadata {
        uuid icon_id FK
        string category
        string alt_text
        json custom_properties
    }

    IconAlias {
        uuid icon_id FK
        string alias
    }

    IconVariant {
        uuid icon_id FK
        string variant_name
        string file_path
    }

3.3 Interface Impact (Before → After)¶

Not applicable — new system addition.

3.4 Alternatives Considered¶

1. Using a third-party icon management service

   • Description: Integrate with an existing icon management service rather than building our own
   • Pros:
     • Faster implementation
     • Professionally maintained
   • Cons:
     • Dependency on external service
     • Limited customization
     • Potential costs
   • Why not chosen: Need for tight integration with our CMS and specific custom requirements

2. Client-side only icon management

   • Description: Handle all icon management in the frontend, using bundled icon sets
   • Pros:
     • Simpler implementation
     • No backend storage requirements
   • Cons:
     • Limited scalability
     • Difficult to update without redeployment
     • No user-contributed icons
   • Why not chosen: Doesn't meet requirement for user uploads and dynamic management

4. Implementation Details¶

4.1 Core Contracts and APIs¶

Icon Upload API¶

POST /api/icons
Content-Type: multipart/form-data

Form Parameters:
- file: The icon file (required)
- name: The icon name (required)
- category: The icon category (required)
- aliases: Comma-separated list of aliases (optional)
- alt_text: Alternative text for accessibility (optional)
- supports_color: Boolean indicating if icon supports color changes (optional, default: false)

Icon Package Upload API¶

POST /api/icon-packages
Content-Type: multipart/form-data

Form Parameters:
- file: The icon package file (zip containing icons) (required)
- name: The package name (required)
- description: The package description (optional)
- metadata: JSON file defining icon names, categories, and aliases (optional)

Icon Search API¶

GET /api/icons/search?query={search_term}&category={category}&limit={limit}&offset={offset}

Query Parameters:
- query: Search term to match against icon names and aliases (optional)
- category: Filter by category (optional)
- limit: Maximum number of results (optional, default: 20)
- offset: Pagination offset (optional, default: 0)

Icon Reference API¶

GET /api/icons/{icon_name}

Path Parameters:
- icon_name: The name of the icon to retrieve

Query Parameters:
- color: Hex color code for SVG icons that support color (optional)
- size: Size in pixels (optional, default: original size)
- variant: Icon variant to retrieve (optional, default: primary)

4.2 Component Architecture¶

Icon Upload Flow¶

1. User submits icon upload form with file and metadata
2. System validates the icon file format and size
3. System extracts metadata from the file if possible (for SVGs: dimensions, color support)
4. System generates a unique identifier for the icon
5. System stores the icon file in the file storage system
6. System creates icon metadata record in the database
7. System returns success response with icon details

Icon Package Upload Flow¶

1. User submits icon package upload form with zip file and metadata
2. System validates the package format and extracts contents
3. System creates an IconPackage record
4. For each icon in the package: a. System validates the icon file b. System extracts or applies metadata from package metadata file c. System stores the icon file d. System creates icon metadata record linked to the package
5. System returns success response with package details and icon count

Icon Search Flow¶

1. User submits search query
2. System queries the database for icons matching the name, aliases, or category
3. System applies pagination and sorting
4. System returns matching icons with their metadata

State Management¶

Icon States:

• Active: Icon is available for use
• Deprecated: Icon is marked for removal but still available for backward compatibility
• Deleted: Icon is no longer available (soft deleted)

Icon Package States:

• Draft: Package is being created or modified
• Published: Package is available for use
• Deprecated: Package is marked for removal but still available
• Deleted: Package is no longer available (soft deleted)

4.4 Error Handling and Edge Cases¶

7. Test Matrix¶

7.1 Unit Coverage¶

• Test icon validation logic
• Test search algorithms
• Test metadata extraction

7.2 Integration Coverage¶

• Test end-to-end icon upload and retrieval
• Test icon package handling
• Test search performance with large datasets

7.3 Regression Coverage¶

• Test file upload validation to prevent malicious files
• Test access control to icon resources
• Test SVG sanitization to prevent XSS attacks

9. Rollout and Migration¶

9.1 Phased Plan¶

Phase 1: Core Icon Management

• Define domain models for Icon and IconPackage
• Implement database schema for icon metadata
• Create file storage integration for icon files
• Implement basic icon upload functionality
• Implement icon retrieval by name

Phase 2: Search and Organization

• Implement icon search functionality
• Add support for icon aliases
• Develop icon categorization system
• Implement icon package upload and extraction

Phase 3: Advanced Features

• Add support for SVG color manipulation
• Implement icon variants (different sizes/styles)
• Add icon analytics (usage tracking)
• Develop administrative tools for icon management

10. Risks and Mitigations¶

12. Changelog¶

References¶

• Current IconPackage aggregate: server/services/loryth-cms/src/loryth/cms/domain/icons/icon_package.py
• UI metadata with icon support: server/libs/loryth-domain/src/loryth/domain/ui/ui_metadata.py