Technology Stack

Relevant source files

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

• package.json
• README.md
• pages/api/dispatch.ts
• tailwind.config.js
• pages/_app.tsx
• postcss.config.js
• prettier.config.js
• pages/_document.tsx

The Heyme application is a full-stack web application built primarily on the Next.js framework, utilizing a modern JavaScript/TypeScript ecosystem. It allows users to record video messages and schedule them for future delivery via email. The architecture integrates a frontend built with React, a backend powered by Next.js API routes, a relational database for storage, and third-party services for email delivery and application monitoring.

This document outlines the core technologies, frameworks, libraries, and services that constitute the application's stack. The stack is designed to be robust, scalable, and maintainable, leveraging popular open-source tools and managed services.

Overall Architecture

The application follows a client-server model where the Next.js application serves both the user-facing frontend and the backend API endpoints. A scheduled job triggers the email dispatch process daily, which queries the database for due messages and uses an external email service to send them.

The diagram below illustrates the high-level architecture and data flow of the Heyme application.

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

Frontend

The frontend is built with Next.js, a React framework that provides server-side rendering, static site generation, and a comprehensive development experience.

Sources: package.json:15, pages/index.tsx

Core Frameworks & Libraries

Library	Version	Description
next	^13.1.6	The core React framework for building the application.
react	^18.2.0	The JavaScript library for building user interfaces.
typescript	^5.0.4	The language used for static typing, enhancing code quality and maintainability.
@next/font	^13.1.6	Optimizes and self-hosts fonts for performance.
next-themes	^0.2.1	Enables light and dark mode theming.
next-seo	^5.15.0	Manages SEO metadata like titles, descriptions, and open graph tags.

Sources: package.json:15-72, pages/_app.tsx:3-12, pages/index.tsx:12-26

UI Components & Styling

Styling is handled by Tailwind CSS, a utility-first CSS framework, configured via tailwind.config.js and processed with PostCSS. The application uses Radix UI primitives for building accessible and unstyled UI components, which are then styled with Tailwind.

Sources: tailwind.config.js, postcss.config.js, package.json:20-44

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: ["pages/**/*.{ts,tsx}", "components/**/*.{ts,tsx}"],
  theme: {
    // ... theme extensions
  },
  plugins: [require("tailwindcss-animate")],
}

This configuration enables dark mode via a class strategy and specifies the files to be scanned for Tailwind utility classes.
Sources: tailwind.config.js:4-10

The application also uses tailwindcss-animate for animations and lucide-react for icons.

Sources: package.json:69, package.json:54

Backend

The backend logic is implemented using Next.js API Routes, which are serverless functions located in the pages/api directory.

Sources: pages/api/dispatch.ts

API & Services

Service/Library	Version	Description
Next.js API Routes	N/A	Server-side endpoints for handling application logic, such as saving message data.
knex	^2.4.2	A SQL query builder for Node.js, used to interact with the MySQL database.
mysql	^2.18.1	The database driver for connecting to the MySQL instance.
zeptomail	^3.0.3	The client library for Zeptomail, used for sending transactional emails.
dayjs	^1.11.7	A lightweight library for parsing, validating, and formatting dates.

Sources: package.json:52-72, pages/api/dispatch.ts, README.md:46-49

Email Dispatch Logic

The core backend functionality is the email dispatch system, handled by the /api/dispatch.ts endpoint. This endpoint is intended to be triggered by a scheduled job. It fetches all videos scheduled for the current day, constructs an HTML email using a template, and sends it via the Zeptomail API.

The following sequence diagram illustrates the email dispatch process:

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

The email body is dynamically generated by replacing placeholders in an HTML template file.

// pages/api/dispatch.ts:9-18
export async function getEmailContent({ watchLink, greeting, body, outro }) {
  let emailContent = Fs.readFileSync(
    Path.resolve("public", "mails", "email.html")
  ).toString()

  emailContent = emailContent.replace("{{REPLACE_WATCH_LINK_HERE}}", watchLink)
  emailContent = emailContent.replace("{{REPLACE_GREETING_HERE}}", greeting)
  emailContent = emailContent.replace("{{REPLACE_BODY_HERE}}", body)
  emailContent = emailContent.replace("{{REPLACE_OUTRO_HERE}}", outro)

  return emailContent
}

Sources: pages/api/dispatch.ts:9-18, public/mails/email.html

Data Storage

The application uses a MySQL database for persistent data storage. The knex library acts as a query builder to interact with the database in a structured way. Key database operations include fetching videos scheduled for the current day and updating their status to sent after dispatch.

Sources: README.md:46, package.json:52, pages/api/dispatch.ts:20-28

External Services

Heyme relies on several external services for core functionality and monitoring.

Service	Purpose	Implementation
Zeptomail	Transactional email delivery.	The zeptomail npm package is used in the /api/dispatch endpoint.
Vercel Analytics	Website traffic and performance analytics.	Integrated via @vercel/analytics/react in _app.tsx.
Highlight.run	Session replay and error monitoring.	Initialized in _app.tsx and wraps the API handler with withHighlight.
Web Media Recorder API	In-browser video and audio recording.	A browser-native API used on the frontend.

Sources: README.md:46-51, package.json:17,45,72, pages/_app.tsx:5,13,28, pages/api/dispatch.ts:99

Development & Tooling

The development environment is supported by a set of tools for code quality, formatting, and testing.

Tool	Purpose	Configuration
ESLint	Code linting to find and fix problems in JavaScript/TypeScript code.	.eslintrc.json (not provided, but inferred from package.json)
Prettier	An opinionated code formatter to ensure consistent code style.	prettier.config.js
Jest	A JavaScript testing framework used for unit tests.	jest.config.js (not provided), test files in tests/
ts-jest	A Jest transformer for TypeScript.	package.json

Sources: package.json:74-98, prettier.config.js, tests/api/dispatch.spec.ts

The Prettier configuration enforces a specific import order, contributing to code organization.

// prettier.config.js
/** @type {import('prettier').Config} */
module.exports = {
  // ... other rules
  importOrder: [
    "^(react/(.*)$)|^(react$)",
    "^(next/(.*)$)|^(next$)",
    "<THIRD_PARTY_MODULES>",
    "",
    "^types$",
    "^@/types/(.*)$",
    // ... more path aliases
  ],
  plugins: ["@ianvs/prettier-plugin-sort-imports"],
}

Sources: prettier.config.js:2-20