Toolbox Card
Data Entity
Description
A structured conversation-starter card or practical resource in the digital peer mentor toolbox. Cards have title, body text, optional media, and category tags. Organization-scoped and cached locally for offline access. Supports text scaling up to 200% for accessibility compliance.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the toolbox card, generated server-side as a UUID v4 | PKrequiredunique |
organization_id |
uuid |
Foreign key reference to the owning organization. All card access is scoped to this value — peer mentors only see cards from their active organization context | required |
title |
string |
Short display title of the card shown in the grid and viewer header. Must be concise enough to render at 200% text scale without truncation in standard card width | required |
body |
text |
Main textual content of the card — conversation prompts, instructions, or resource description. Rendered in Card Viewer Widget with dynamic text scaling support up to 200% | required |
media_url |
string |
Optional URL pointing to a media asset (image or illustration) associated with the card. Must be an absolute HTTPS URL. References organization-scoped object storage. Null when no media is attached | - |
media_type |
enum |
Discriminator for the media asset type, used by Card Viewer Widget to select the correct rendering strategy. Must be set when media_url is non-null | - |
category_tags |
json |
Array of string category labels used for client-side filtering in Talking Cards Screen and Card Search & Filter Widget. Examples: ['conversation', 'practical', 'mental-health', 'activity-ideas']. Stored as a JSONB array in PostgreSQL for efficient GIN indexing | required |
sort_order |
integer |
Numeric sort position within the organization's card collection. Lower values appear first in the grid. Gaps are allowed to enable insertion without renumbering. Default is assigned as (max existing sort_order + 10) on creation | required |
is_active |
boolean |
Soft-visibility flag. Inactive cards are excluded from API responses to mobile clients but remain in the database. Allows organization admins to temporarily hide cards without deleting them | required |
created_by |
uuid |
User ID of the organization administrator or global administrator who created the card. Used for audit purposes. References the users table | required |
version |
integer |
Monotonically increasing version counter incremented on every update. Used by Toolbox Offline Cache Infrastructure to detect stale cached content without downloading full payloads — client compares its cached version against the API response version | required |
created_at |
datetime |
ISO 8601 UTC timestamp of record creation. Set server-side on insert, immutable thereafter | required |
updated_at |
datetime |
ISO 8601 UTC timestamp of the most recent update to any mutable field. Updated automatically by a database trigger or ORM hook on every write | required |
Database Indexes
idx_toolbox_card_organization_id
Columns: organization_id
idx_toolbox_card_org_sort_order
Columns: organization_id, sort_order
idx_toolbox_card_org_active
Columns: organization_id, is_active
idx_toolbox_card_category_tags_gin
Columns: category_tags
idx_toolbox_card_version
Columns: organization_id, version
Validation Rules
title_not_empty
error
Validation failed
body_not_empty
error
Validation failed
media_url_https_only
error
Validation failed
category_tags_string_array
error
Validation failed
sort_order_non_negative
error
Validation failed
organization_id_exists
error
Validation failed
created_by_is_admin
error
Validation failed
Business Rules
organization_scoping
A toolbox card is visible only to users whose active organization context matches the card's organization_id. The Toolbox Content Repository must always include organization_id as a WHERE clause condition. Cross-organization card access is forbidden even for Global Administrators operating in another org's context
active_cards_only_for_mobile
Mobile API endpoints serving the Talking Cards Screen must only return cards where is_active = true. Inactive cards are accessible only via the admin interface for editing or reactivation. This ensures peer mentors never see draft or deprecated content
media_url_requires_media_type
If media_url is non-null, media_type must also be set to a valid non-null enum value. Conversely, if media_url is null, media_type must be null or 'none'. Ensures Card Viewer Widget always has a valid rendering strategy for any media present
sort_order_default_assignment
On creation, if sort_order is not explicitly provided, the system assigns (MAX(sort_order) + 10) within the organization's card set. This preserves room for future insertions between existing cards without requiring a full renumber operation
version_increment_on_update
Every update to a mutable field (title, body, media_url, media_type, category_tags, sort_order, is_active) must atomically increment the version counter. This enables the Toolbox Offline Cache Infrastructure to perform lightweight version-check cache invalidation without re-fetching full payloads
min_one_category_tag
Every card must belong to at least one category tag. An empty category_tags array is rejected at creation and update time. This ensures the client-side category filter in Card Search & Filter Widget always has meaningful groupings
admin_role_required_for_write
Create, update, and delete operations on toolbox cards are restricted to users with Organization Administrator or Global Administrator roles. Peer Mentors and Coordinators have read-only access via the mobile API. Role validation is enforced at the service layer before any database write
offline_cache_consistency
When the mobile client fetches cards, the API response includes the current version for each card. The Toolbox Offline Cache Infrastructure compares versions and only fetches updated content, minimizing bandwidth. Cache invalidation occurs on organization context switch or when the server reports a higher version than the cached record
CRUD Operations
Storage Configuration
Entity Relationships
An organization maintains its own library of talking cards and toolbox content for peer mentors