Stories Module

[andreyasko]

The module will allow users to share short-lived, ephemeral content (photos, videos, or text) that is visible for a limited time (e.g., 24 hours) and displayed in a dedicated, visually appealing carousel or timeline format.

1. General Module Design

The “Stories” module will enable users to:

• Create short-lived photo, video, or text-based stories.

• View stories in a carousel at the top of the feed (or a dedicated section).

• Automatically delete stories after their expiration period (e.g., 24 hours).

• Enable analytics (e.g., viewers list) for creators to see who viewed their stories.

2. Key Features

User Features:

• Create Stories: Upload photos, videos, or text with optional effects, stickers, and captions.

• View Stories: Users can view their own stories and those of others they follow.

• Auto-Advance: Stories play one after another automatically.

• Duration: Each story is visible for a limited time (e.g., 5-10 seconds per story, configurable).

Admin Features:

• Configure expiration period for stories.

• Moderate and remove inappropriate stories.

• Enable/disable specific features (e.g., effects, stickers).

3. Database Design

Table: stories

Column Name Data Type Description

id INT (PK, AUTO_INCREMENT) Unique identifier for each story.

user_id INT (FK) ID of the user who created the story.

media_type ENUM(‘photo’, ‘video’, ‘text’) Type of the story content.

media_url TEXT URL of the uploaded media (photo/video).

text_content TEXT Content for text-based stories.

caption VARCHAR(255) Optional caption for the story.

created_at TIMESTAMP Time when the story was created.

expires_at TIMESTAMP Time when the story will expire.

status ENUM(‘active’, ‘expired’, ‘deleted’) Story’s status.

Table: stories_views

Column Name Data Type Description

id INT (PK, AUTO_INCREMENT) Unique identifier for each view.

story_id INT (FK) ID of the story viewed.

user_id INT ID of the user who viewed the story.

viewed_at TIMESTAMP Time when the story was viewed.

4. Story Creation Logic

Workflow:

1. User uploads a photo/video or writes text.

2. The system generates the media URL (for uploads) and stores metadata.

3. expires_at is automatically set based on the configured expiration period (e.g., 24 hours).

SQL Example:

-- Insert a new story

INSERT INTO stories (user_id, media_type, media_url, text_content, caption, created_at, expires_at, status)

VALUES (1, 'photo', 'https://example.com/photo.jpg', NULL, 'Check this out!', NOW(), DATE_ADD(NOW(), INTERVAL 24 HOUR), 'active');

5. Viewing Stories

Retrieval Logic:

1. Fetch all active stories of the users a viewer follows, ordered by created_at.

2. Include a flag to indicate whether the current viewer has already seen each story.

SQL Example:

-- Get active stories for a user's feed

SELECT s.*, sv.user_id AS viewer_id

FROM stories s

LEFT JOIN stories_views sv ON s.id = sv.story_id AND sv.user_id = 1

WHERE s.status = 'active' AND s.expires_at > NOW()

  AND s.user_id IN (SELECT followed_id FROM follows WHERE follower_id = 1)

ORDER BY s.created_at DESC;

6. Displaying Stories

Frontend Logic:

1. Carousel Display:

• Display stories as circular profile icons in a horizontal scroll view.

• Highlight stories not yet viewed.

2. Story Playback:

• Show full-screen stories one by one.

• Auto-advance to the next story after a timer or user interaction.

Backend API:

• Fetch Stories: Return all active stories for the user.

• Mark Story as Viewed: Record the viewer in the stories_views table.

7. Story Expiration

Logic:

1. A cron job or scheduled task runs periodically (e.g., every hour) to:

• Mark stories as expired if expires_at <= NOW().

• Clean up expired stories (optional) to reduce database size.

SQL Example:

-- Mark expired stories

UPDATE stories

SET status = 'expired'

WHERE status = 'active' AND expires_at <= NOW();

8. Post Management

Editing:

• Stories cannot be edited once posted. Users must delete and recreate them.

Deletion:

• Users can manually delete their stories before expiration, setting status = 'deleted'.

SQL Example:

-- Delete a story

UPDATE stories

SET status = 'deleted'

WHERE id = 1 AND user_id = 1;

9. Performance Optimization

1. Indexing:

• Index user_id for fast retrieval of stories by user.

• Index expires_at to efficiently clean up expired stories.

2. Preloading Media:

• Use lazy loading for videos and photos to reduce initial load time.

• Preload upcoming stories for smooth playback.

3. View Caching:

• Cache frequently accessed stories for popular users (e.g., Redis).

10. Expected Outcome

• A Stories module allowing users to post ephemeral content.

• A carousel interface for viewing and interacting with stories.

• Efficient handling of story expiration and database cleanup.

• Compatibility with small-scale and scalable deployments.

[linear]

UNA-294 Stories Module

[AntonLV]

@andreyasko could you please provide me with Studio icon.

[AntonLV]

Related commit 7dee374