# Asset Tagging System

The tagging system provides a flexible way to organize, categorize, and filter assets across your Digital Asset Manager. Tags are lightweight, user-created labels that help you quickly locate and group related media files.

## Overview

Tags are: - User-managed — Create and apply tags freely to any asset - Searchable — Filter entire asset library by single or multiple tags - Autocompleted — Suggestions based on existing tags across your library - Persistent — Stored in the database for instant access - Lowercase-normalized — Consistent across all assets

## Quick Start

### Adding Tags to an Asset

1. Open any asset in the Asset Detail View
2. Click the Edit button next to "Tags" section
3. Type a tag name (e.g., `client`, `2024-project`, `video-edit`)
4. Press Enter or click Add button
5. See suggested tags from your library below the input
6. Click Save Tags to persist or Cancel to discard

### Filtering Assets by Tag

1. In Asset Library Dashboard, scroll to the Tags section
2. All available tags load as filter buttons
3. Click any tag to instantly show only assets with that tag
4. Click Clear to reset filters

### Removing Tags

In tag editor mode, each tag has a × button to remove it before saving.

## API Reference

### List All Tags

    GET /api/assets/tags/list

Response:

    {
      "success": true,
      "tags": ["client", "video", "project-alpha", "2024"],
      "count": 4
    }

### Get Asset Tags

    GET /api/assets/<asset_id>/tags

Response:

    {
      "success": true,
      "asset_id": 123,
      "tags": ["video", "client"]
    }

### Update Asset Tags (Bulk Replace)

    PUT /api/assets/<asset_id>/tags
    Content-Type: application/json

    {
      "tags": ["tag1", "tag2", "tag3"]
    }

Response:

    {
      "success": true,
      "asset_id": 123,
      "tags": ["tag1", "tag2", "tag3"],
      "message": "Updated 3 tags"
    }

### Add Single Tag

    POST /api/assets/<asset_id>/tags
    Content-Type: application/json

    {
      "tag": "new-tag"
    }

Response:

    {
      "success": true,
      "asset_id": 123,
      "tags": ["tag1", "tag2", "new-tag"],
      "message": "Added tag: new-tag"
    }

### Remove Single Tag

    DELETE /api/assets/<asset_id>/tags/<tag_name>

Response:

    {
      "success": true,
      "asset_id": 123,
      "tags": ["tag1", "tag2"],
      "message": "Removed tag: new-tag"
    }

### Filter Assets by Tag

    GET /api/assets/filter?tag=video&page=1&limit=20

Response:

    {
      "success": true,
      "tag": "video",
      "assets": [
        {
          "id": 101,
          "title": "Project_Alpha_v2",
          "filename": "project_alpha_v2.jpg",
          "mime_type": "image/jpeg",
          "size": 4200000,
          "url": "...",
          "metadata": "{...}",
          "created_at": "2025-12-15T10:30:00",
          "tags": "video,client"
        }
      ],
      "page": 1,
      "limit": 20,
      "total": 5
    }

## Database Schema

Tags are stored in the `assets` table's `tags` column (TEXT):

    -- Column definition
    tags TEXT DEFAULT ''

    -- Format: comma-separated, lowercase
    -- Example: "client,video,project-alpha,2024"

### Storage Details

Field | Type | Notes
--- | --- | ---
`tags` | TEXT | Comma-separated, lowercase tags. Empty string if no tags.

Why comma-separated? - Simple, human-readable format - Efficient LIKE-based searching - No need for separate tags table for basic use - Easy to extend to junction table later for multi-user permissions

## Best Practices

### Naming Conventions

    ✓ Lowercase         client, video-edit, 2024-q1
    ✓ Use hyphens       project-alpha, high-priority
    ✓ Descriptive       color-grading, client-review

    ✗ Mixed case        Client, VideoEdit (normalized to lowercase)
    ✗ Spaces            "video edit" → use hyphen instead
    ✗ Special chars     avoid @#$% except hyphens

### Tag Organization Strategy

By Client/Project:

    client-abc, client-xyz, project-mars-city

By Media Type:

    video, image, audio, document

By Status:

    draft, approved, archived, published

By Studio/Department:

    film-editing, photography, graphic-arts, podcasting

Combine tags for powerful filtering: - Asset tagged `video,client,approved` shows in filters for any of these - Multiple tag filters could be added in future

## Use Cases

### Marketing Team

- Tag assets by campaign: `campaign-2024-spring`, `campaign-holiday`
- Tag by deliverable: `social-media`, `web`, `print`
- Tag by status: `approved`, `draft`, `archived`

### Film Production

- Tag by scene: `scene-01`, `scene-02`
- Tag by take: `take-01`, `take-final`
- Tag by status: `raw-footage`, `color-graded`, `final`

### Photography Studio

- Tag by photoshoot: `photoshoot-product-2024`, `photoshoot-event-dec`
- Tag by edit status: `unedited`, `edited`, `retouched`
- Tag by usage: `website`, `print-catalog`, `client-delivery`

### Asset Library Management

- Tag by source: `from-google-drive`, `from-network-share`, `uploaded-local`
- Tag by date: `2024-q1`, `2024-q2`, `archive-2023`
- Tag by quality: `high-res`, `web-ready`, `thumbnail-only`

## Limitations & Future Enhancements

### Current Limitations

- Single tag per search — Filter by one tag at a time
- No tag hierarchy — No parent/child tag relationships
- No permissions — All users see and can edit all tags
- No tag descriptions — Tags are label-only

### Planned Enhancements

1. Multi-tag filtering — `?tags=video,client,approved`
2. Tag hierarchy — `video/footage`, `video/edit`
3. Tag analytics — Most-used tags, tag cloud visualization
4. Smart suggestions — Suggest tags based on file type or content
5. Tag validation — Admin-controlled tag whitelist
6. Bulk tag operations — Apply tags to multiple assets at once
7. Tag synonyms — `hdv` → `video`, `pic` → `image`
8. User-specific tags — Per-user tag visibility and permissions

## Troubleshooting

### Tags Not Appearing

Problem: Added a tag but it's not showing in the filter list.

Solution: - Reload the page — filter buttons are loaded on page init - Verify tag was saved — check Asset Detail View confirmation - Check spelling — tags are case-insensitive but must match exactly

### Tag Suggestions Not Loading

Problem: Autocomplete suggestions are empty.

Solution: - No other assets have tags yet — create a few tagged assets first - Check browser console for errors - Verify `/api/assets/tags/list` is responding (check Network tab)

### Can't Edit Tags

Problem: Edit button doesn't work or tags won't save.

Solution: - Ensure you're logged in — tag edit requires authentication - Check for errors in browser console - Try refreshing the page - Verify server is running (check Flask logs)

## Related Documentation

- Database Schema — Asset table structure
- Backend API — Complete API reference
- Frontend Components — Asset detail view and dashboard

« Previous Next »