Talking Card
Data Entity
Description
A conversation-starter card used by peer mentors to facilitate structured conversations with contacts. Cards are browsable, filterable, and available offline. The catalog is platform-managed (shared across organizations) with optional organization-specific additions.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
Owning organization for org-specific cards. NULL means platform-wide card visible to all tenants. | - |
title |
string |
Short display title of the card shown in the browser grid | required |
body_text |
text |
Main conversational prompt or question text displayed on the card face | - |
category |
string |
Thematic grouping used for filtering in the browser (e.g. 'daily_life', 'health', 'family', 'goals') | - |
tags |
json |
Array of string tags for secondary filtering and search (e.g. ['blindness','independent_living']) | - |
content_type |
enum |
Determines which content fields are rendered on the card | required |
image_url |
string |
URL to the card illustration or photo. Required when content_type is 'image' or 'image_text'. | - |
image_alt_text |
string |
WCAG-required accessible description of the card image for screen readers | - |
language |
string |
BCP-47 language code of the card content. Supports Norwegian Bokmål (nb), Nynorsk (nn), Northern Sami (se), English (en). | required |
sort_order |
integer |
Display order within a category. Lower values appear first. | - |
is_active |
boolean |
Whether this card is currently visible in the browser. Inactive cards are hidden without deletion. | required |
source_refs |
json |
Provenance references (e.g. original content source, editor attribution). Array of string identifiers. | - |
created_by |
uuid |
User who created an org-specific card. NULL for platform-managed cards. | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last modification timestamp | required |
Database Indexes
idx_talking_cards_organization_id
Columns: organization_id
idx_talking_cards_category_language
Columns: category, language
idx_talking_cards_is_active_sort
Columns: is_active, sort_order
Validation Rules
title_not_empty
error
Validation failed
language_valid_bcp47
error
Validation failed
body_text_required_for_text_type
error
Validation failed
tags_is_string_array
error
Validation failed
sort_order_non_negative
error
Validation failed
Business Rules
platform_cards_immutable
Cards with organization_id IS NULL are platform-managed and cannot be modified or deleted by any organization-scoped request. Only internal sync operations may write them.
org_card_tenant_isolation
Cards with a non-null organization_id are only returned to users whose active session belongs to that organization. Cross-tenant card reads are rejected.
image_requires_alt_text
When content_type is 'image' or 'image_text', image_alt_text must be non-empty to satisfy WCAG 2.2 AA requirements for non-text content.
image_url_required_for_image_type
If content_type is 'image' or 'image_text', image_url must be provided.
offline_catalog_sync
The full set of active cards for the user's organization (platform cards + org-specific cards) must be synced to offline storage during app startup or background sync so the toolbox is usable without connectivity.
inactive_cards_hidden
Cards with is_active = false must not appear in the browser or be returned by list endpoints. They are retained for audit/recovery purposes.