Feature: Message Composition
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The core feature of the Heyme application is the ability for users to compose and schedule messages for their future selves or for others. This system allows a user to record a video message, specify a delivery date, and have it sent via email when that date arrives. The primary goal is to create a "time capsule" that serves as a motivational tool and a reminder of past goals and aspirations.
The overall architecture involves a Next.js frontend for user interaction (recording and scheduling), a MySQL database for storing message metadata, and a serverless API endpoint responsible for dispatching the messages at the scheduled time using the Zeptomail transactional email service.
Sources: README.md:5-13, pages/api/dispatch.ts, pages/index.tsx:49-54
System Architecture
The message composition and delivery feature is composed of a frontend user flow, a backend API for processing, and an email delivery service.
High-Level Flow
This diagram illustrates the end-to-end user journey from creating a message to receiving it in the future.
Frontend Components
1. Entry Point
The user journey begins on the main landing page, which prompts the user to create a message.
- A prominent "Record a message" button directs the user to the
/recordingpage to begin the composition process. - The page also features a video demonstrating the application's use.
Sources: pages/index.tsx:37-39, pages/index.tsx:49-54
2. Success and Sharing
After a user successfully submits a message, they are redirected to a success page.
- This page confirms that the message is scheduled.
- It encourages social sharing using the Web Share API if available, with fallbacks to direct links for Facebook, LinkedIn, and Twitter.
- An animated GIF and a "Woo-hoo!" message enhance the user experience.
The handleShareClick function attempts to use the native navigator.share for a better mobile experience.
Sources: components/success.tsx:10-13, components/success.tsx:24-34, components/success.tsx:46-58
Backend: Message Dispatching
The core logic for sending scheduled messages resides in the /api/dispatch.ts API route. This endpoint is designed to be called periodically (e.g., by a cron job) to check for and send any messages scheduled for the current day.
Sources: pages/api/dispatch.ts
API Endpoint: POST /api/dispatch
This endpoint orchestrates the entire dispatch process.
Dispatch Logic Flow
The following diagram details the sequence of operations within the handleDispatchEmails function.
Sources: pages/api/dispatch.ts:34-89
Key Functions
The dispatch logic is broken down into several helper functions.
| Function | Description | Source File |
|---|---|---|
handleDispatchEmails | Main handler that connects to the DB, fetches videos, and orchestrates the email sending loop. | pages/api/dispatch.ts:34 |
fetchAllVideosForToday | Queries the Videos table for all records where the send_at column matches the current date. | pages/api/dispatch.ts:20 |
updateVideoToSent | Updates a video's record in the database, setting the sent flag to 1 to prevent re-sending. | pages/api/dispatch.ts:26 |
getEmailContent | Reads an HTML email template from the filesystem and replaces placeholders with dynamic video data. | pages/api/dispatch.ts:9 |
Email Generation
Email content is dynamically generated by populating a static HTML template.
Email Generation Sequence
This diagram shows how the main handler uses getEmailContent to prepare the email body.
Email Template
The email body is sourced from a template file which contains placeholders for dynamic content.
- File:
public/mails/email.html - Placeholders:
{{REPLACE_GREETING_HERE}}{{REPLACE_WATCH_LINK_HERE}}{{REPLACE_BODY_HERE}}{{REPLACE_OUTRO_HERE}}
This approach separates the email's structure and styling from the business logic. The getEmailContent function is tested to ensure these replacements work correctly.
Sources: public/mails/email.html, tests/api/dispatch.spec.ts:6-22
Data Model
The application relies on a Videos table in a MySQL database to store message information. The schema can be inferred from its usage in the dispatch logic.
Videos Table Schema
This ER diagram shows the inferred structure of the Videos table.
Field Descriptions
| Column | Type | Description | Inferred From -
| id | int | The primary key for the video record. | pages/api/dispatch.ts:27 -
| send_at | date | The date the message is scheduled to be sent. | pages/api/dispatch.ts:22 -
| sent | int | A boolean flag (0 for not sent, 1 for sent). | pages/api/dispatch.ts:28 -
| send_to | string | Determines the email subject and greeting. Value is likely "yourself". | pages/api/dispatch.ts:55 -
| created_at | string | The original creation date, used in the email greeting. | pages/api/dispatch.ts:57 -
| email | string | The recipient's email address. | pages/api/dispatch.ts:63 -