External Resource
Data Entity
Description
A curated external URL resource configured by the organization and accessible from the app's Resources section. Peer mentors can access links to training materials, guidelines, support sites, and partner services. Resources are organization-scoped and cached locally for offline availability.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key — unique identifier for the external resource record | PKrequiredunique |
organization_id |
uuid |
Foreign key to organizations table. All resources are scoped to a single organization; peer mentors see only resources belonging to their active organization context. | required |
title |
string |
Display name of the resource shown on the resource card in the Resources Screen. Must be concise and descriptive. Organization labels system may override display terminology. | required |
description |
text |
Optional short description providing context about the resource's purpose, shown below the title on the resource card. Helps peer mentors decide whether to open the link. | - |
url |
string |
The external URL to open when the resource is tapped. Must be a fully-qualified HTTPS URL. HTTP URLs are rejected to prevent insecure navigation. Validated at save time by the organization settings service. | required |
category |
enum |
Logical grouping of the resource for display filtering and icon assignment on the Resources Screen. Categories map to icon assets in the design system. | required |
launch_mode |
enum |
Determines how the URL is opened when tapped. 'system_browser' delegates to the OS default browser. 'in_app_webview' opens within the app via webview_flutter, keeping users in-app and supporting back navigation. | required |
display_order |
integer |
Integer position controlling the display order of resources within a category on the Resources Screen. Lower values appear first. Defaults to 0; resources with equal order are sorted by title. | - |
is_active |
boolean |
Controls visibility of the resource to peer mentors. Inactive resources are excluded from the Resources Screen and from the locally cached resource list. Allows admins to hide resources without deleting them. | required |
icon_key |
string |
Optional key referencing a design-system icon asset to display on the resource card alongside the title. When null the category default icon is used. Must match a key in the app's bundled icon registry. | - |
created_by |
uuid |
Foreign key to users table recording which Organization Administrator or Global Administrator created this resource. Used for audit trail; does not affect resource visibility. | - |
created_at |
datetime |
UTC timestamp of record creation. Set once on insert and never updated. Used for cache ETag generation and audit purposes. | required |
updated_at |
datetime |
UTC timestamp of the last modification. Updated on every write. Consumed by the Resource Repository's ETag/last-modified cache invalidation strategy to determine whether the mobile client's cached list is stale. | required |
Database Indexes
idx_external_resource_organization_id
Columns: organization_id
idx_external_resource_org_active_order
Columns: organization_id, is_active, display_order
idx_external_resource_org_category
Columns: organization_id, category
idx_external_resource_updated_at
Columns: organization_id, updated_at
Validation Rules
title_not_empty
error
Validation failed
url_format_valid
error
Validation failed
url_scheme_https_required
error
Validation failed
category_valid_enum_value
error
Validation failed
launch_mode_valid_enum_value
error
Validation failed
description_max_length
error
Validation failed
display_order_non_negative
error
Validation failed
organization_id_exists
error
Validation failed
icon_key_max_length
warning
Validation failed
Business Rules
organization_scope_isolation
A resource belongs exclusively to one organization. The Resource Repository must always scope all queries with the authenticated user's active organization_id. A peer mentor from Organization A must never see resources configured by Organization B, even if their URLs are identical.
https_only_urls
All resource URLs must use the HTTPS scheme. HTTP URLs expose peer mentors to insecure connections and are rejected at save time. This rule prevents man-in-the-middle attacks when users open links on untrusted networks.
inactive_resources_excluded_from_cache
When the Resource Repository fetches the organization's resource list for caching on the mobile device, it must only include records where is_active = true. Deactivated resources must not appear in the Resources Screen even if a stale cache entry exists.
cache_invalidation_on_update
Any create, update, or delete operation on an external_resource must invalidate the mobile client cache for the affected organization. The Resource Repository uses the most recent updated_at timestamp across the organization's resources as an ETag. Clients that send a matching ETag receive a 304 Not Modified response; stale clients receive the full updated list.
admin_only_mutation
Only users with Organization Administrator or Global Administrator roles may create, update, or delete external resources. Peer Mentors and Coordinators have read-only access via the mobile Resources Screen.
offline_cache_must_reflect_active_only
The locally cached resource list stored for offline availability must be refreshed on every successful online fetch and must only contain is_active = true records. The cached payload must never include soft-deactivated or deleted resources.
CRUD Operations
Storage Configuration
Entity Relationships
An organization curates its own list of external resource links for peer mentors