Data Flow

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pages/api/dispatch.ts
• pages/index.tsx
• public/mails/email.html
• tests/api/dispatch.spec.ts
• package.json

The data flow in Heyme is centered around capturing a user's video message, storing it, and delivering it at a future date via email. The process involves a Next.js frontend for user interaction, a MySQL database for persistent storage of message metadata, and a third-party email service (Zeptomail) for dispatching the notifications.

A key component of this system is a scheduled API endpoint, /api/dispatch, which is responsible for checking for messages due for delivery each day, constructing a personalized email, sending it to the recipient, and updating the message status to prevent duplicate sends. The overall architecture is designed to be simple and effective for its purpose of sending messages to the future.

System Architecture

The application is built on a modern web stack, utilizing several key services to manage the data lifecycle. The frontend is a Next.js application, which communicates with a backend API. Data is stored in a MySQL database, and transactional emails are handled by Zeptomail.

Sources: README.md, package.json

High-Level Component Interaction

The following diagram illustrates the main components and their interactions as described in the project's architecture overview.

This diagram shows the flow from the user interacting with the frontend to the backend services handling storage and email dispatch.

Sources: README.md, pages/api/dispatch.ts

Data Storage

The primary data entity is the Videos table, which resides in a MySQL database. This table stores all the necessary information about a recorded message, including recipient details, scheduling information, and its delivery status.

Sources: README.md, pages/api/dispatch.ts:28-31

Videos Table Schema

Based on the queries in pages/api/dispatch.ts, the Videos table can be inferred to have the following structure.

This ER diagram outlines the fields of the Videos table used by the dispatch logic.

Sources: pages/api/dispatch.ts:28-31, 34-36, 61-63

Column	Type (Inferred)	Description	Source File Reference
id	int / number	Unique identifier for the video record.	pages/api/dispatch.ts:34
send_at	date	The date the notification email should be sent. Formatted as 'YYYY-MM-DD'.	pages/api/dispatch.ts:30
sent	boolean / int	A flag indicating if the email has been dispatched (1 for true).	pages/api/dispatch.ts:34, 61
send_to	string	Indicates if the message is for 'yourself' or someone else.	pages/api/dispatch.ts:63
email	string	The recipient's email address.	pages/api/dispatch.ts:72
created_at	datetime	The timestamp when the video message was created.	pages/api/dispatch.ts:65

Email Dispatch Logic

The core of the automated data flow is the /api/dispatch endpoint, which handles the process of sending out scheduled emails. This process is intended to be run on a schedule (e.g., a daily cron job).

Sources: pages/api/dispatch.ts

Dispatch Sequence

The following sequence diagram details the step-by-step process executed by the handleDispatchEmails function when the /api/dispatch endpoint is triggered.

This diagram shows the interaction between the API, the database, and the Zeptomail service to deliver the messages.

Sources: pages/api/dispatch.ts:38-103

Key Functions

• handleDispatchEmails(request, response): The main handler for the API route. It orchestrates the entire process from DB connection to email sending and status updates.
• fetchAllVideosForToday(connection): Executes a SQL SELECT query to retrieve all records from the Videos table where the send_at column matches the current date.
• updateVideoToSent(connection, id): Executes a SQL UPDATE query to set the sent flag to 1 for a given video ID, preventing it from being sent again.
• getEmailContent(options): Reads an HTML email template from the filesystem and populates it with dynamic data.

Sources: pages/api/dispatch.ts:11-36, 38-103

Email Content Generation

Emails are generated dynamically using a static HTML template and a helper function that replaces placeholders with video-specific data.

Sources: pages/api/dispatch.ts:11-23, public/mails/email.html, tests/api/dispatch.spec.ts

Template Placeholders

The getEmailContent function reads the template from public/mails/email.html and replaces the following placeholders.

Placeholder	Replacement Value
{{REPLACE_WATCH_LINK_HERE}}	The unique URL to watch the video, e.g., https://heyme.io/watch/{video.id}.
{{REPLACE_GREETING_HERE}}	A dynamic greeting based on whether the user sent the message to themselves.
{{REPLACE_BODY_HERE}}	A static body text explaining the service.
{{REPLACE_OUTRO_HERE}}	A static closing message.

This process is verified by unit tests.

Sources: public/mails/email.html:255, 279, 345, 354, pages/api/dispatch.ts:16-19, tests/api/dispatch.spec.ts:7-24

Content Generation Flow

This flowchart shows the simple substitution process for creating the email body.

Sources: pages/api/dispatch.ts:11-23