Home

Relevant source files

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

• README.md
• QUICK_START.md
• API_REFERENCE.md
• mono-repo.md
• package.json
• packages/core/src/index.ts
• packages/core/prisma/schema.prisma
• packages/core/src/types/dataModels.ts
• packages/core/src/api/middleware/authMiddleware.ts
• packages/core/src/api/controllers/messageController.ts
• packages/client/src/index.ts

MessageJS is a service that enables web developers to send messages via multiple chat platforms like WhatsApp, Telegram, and SMS through a simple, unified API and SDK. The system is designed to be similar to services like EmailJS or SendGrid, but focused on messaging applications, ensuring that provider credentials are never exposed to the frontend.

The project is currently in an early development stage, with the core architecture, type system, and monorepo structure established. The backend API and database layer are in progress.

Sources: [README.md:12-14](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L12-L14), [README.md:60-62](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L60-L62), [QUICK_START.md:11-12](https://github.com/1cbyc/messagejs/blob/HEAD/QUICK_START.md#L11-L12)

System Architecture

The overall architecture of MessageJS follows a clear, multi-layered approach, from the client-facing SDK to the third-party messaging APIs. The project is structured as a monorepo to manage its different packages.

Sources: [README.md:46-48](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L46-L48), [mono-repo.md](https://github.com/1cbyc/messagejs/blob/HEAD/mono-repo.md)

High-Level Flow

The data flow for sending a message begins with the client SDK, which communicates with the backend API. The API then routes the request to the appropriate connector, which in turn interacts with the third-party messaging service.

This diagram illustrates the high-level message sending flow.

Sources: [README.md:46-48](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L46-L48)

Monorepo Structure

The project utilizes a monorepo structure to manage its distinct but related packages. The root package.json defines workspaces for all packages located in the packages/* directory.

Package	Description
@messagejs/core	The Node.js/Express backend API server.
@messagejs/client	The frontend SDK for browsers and Node.js environments.
@messagejs/dashboard	A React/Next.js application for managing projects, connectors, and viewing logs.
@messagejs/shared-types	Shared TypeScript types used across packages (mentioned in mono-repo.md).
docs	Project documentation.
examples	Example applications demonstrating SDK usage.

Sources: [README.md:21-26](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L21-L26), [mono-repo.md](https://github.com/1cbyc/messagejs/blob/HEAD/mono-repo.md), [package.json:6-8](https://github.com/1cbyc/messagejs/blob/HEAD/package.json#L6-L8)

Data Model

The core data structures of MessageJS are defined in a Prisma schema and corresponding TypeScript interfaces. The database uses PostgreSQL.

Sources: [packages/core/prisma/schema.prisma](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/prisma/schema.prisma), [packages/core/src/types/dataModels.ts](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/dataModels.ts)

Entity Relationship Diagram

The following diagram shows the relationships between the main database models. A User can have multiple Projects. Each Project can have multiple Services (Connectors), Templates, and MessageLogs.

Sources: [packages/core/prisma/schema.prisma:41-105](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/prisma/schema.prisma#L41-L105)

Core Data Models

User

Represents a developer who owns projects in the system.

Field	Type	Description
id	string	Unique identifier.
email	string	User's unique email address.
passwordHash	string	Hashed password for authentication.

Sources: [packages/core/prisma/schema.prisma:41-47](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/prisma/schema.prisma#L41-L47), [packages/core/src/types/dataModels.ts:8-15](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/dataModels.ts#L8-L15)

Project

A container for API keys, connectors, and message logs.

Field	Type	Description
id	string	Unique identifier.
name	string	Name of the project.
apiKey	string	Unique API key for the project.
userId	string	Foreign key to the User who owns the project.

Sources: [packages/core/prisma/schema.prisma:49-59](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/prisma/schema.prisma#L49-L59), [packages/core/src/types/dataModels.ts:21-27](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/dataModels.ts#L21-L27)

Connector (Service)

Represents the configuration for a third-party messaging service (e.g., WhatsApp, Twilio). In the Prisma schema, this is named Service.

Field	Type	Description
id	string	Unique identifier.
type	ConnectorType	The type of connector (WHATSAPP, TELEGRAM, TWILIO_SMS).
credentialsEncrypted	string	AES-256 encrypted credentials.
projectId	string	Foreign key to the Project.

Sources: [packages/core/prisma/schema.prisma:61-71](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/prisma/schema.prisma#L61-L71), [packages/core/src/types/dataModels.ts:47-57](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/dataModels.ts#L47-L57)

MessageLog

A log entry for a single message sent through the system.

Field	Type	Description
id	string	Unique identifier.
status	MessageStatus	The lifecycle status of the message (QUEUED, SENT, FAILED, etc.).
recipient	string	The recipient's identifier (e.g., phone number).
externalMessageId	string	The ID from the third-party provider.
projectId	string	Foreign key to the Project.
serviceId	string	Foreign key to the Service used.

Sources: [packages/core/prisma/schema.prisma:82-97](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/prisma/schema.prisma#L82-L97), [packages/core/src/types/dataModels.ts:71-86](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/dataModels.ts#L71-L86)

Core Components

@messagejs/core (Backend API)

The backend is an Express.js application responsible for handling API requests, authentication, and orchestrating message sending.

• Entry Point: The server is initialized in packages/core/src/index.ts, which sets up the Express app, middleware, and a health check route at /.
• API Routes: The primary route for sending messages is mounted at /api/v1/messages.
• Authentication: Routes are protected by an API key validation middleware, validateApiKey. This middleware checks for a Bearer token in the Authorization header. The current implementation uses a mock API key for validation.
• Controllers: The messageController contains the logic for the /api/v1/messages endpoint. It receives a request, and its intended function is to validate input, fetch connector/template details, and queue a message for sending.

Sources: [packages/core/src/index.ts](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/index.ts), [packages/core/src/api/middleware/authMiddleware.ts](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/api/middleware/authMiddleware.ts), [packages/core/src/api/controllers/messageController.ts](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/api/controllers/messageController.ts)

@messagejs/client (Client SDK)

The client SDK provides a simple interface for web and Node.js applications to interact with the MessageJS API.

• Singleton Instance: The SDK exports a singleton instance named messagejs for easy integration.
• Initialization: The init() method must be called first to configure the SDK with a project's API key and an optional API base URL.
• Sending Messages: The sendMessage() method sends a request to the backend API. It takes the connectorId, templateId, to, and variables as parameters.

// Example SDK Usage
import messagejs from 'messagejs-client';

// Initialize with API key and project ID
messagejs.init(
  'sk_live_abc123def456...', // Your API key
  'proj_xyz789',             // Your project ID
);

// Send a message
const result = await messagejs.sendMessage({
  to: '+1234567890',
  message: 'Hello from MessageJS!',
  connector: 'whatsapp'
});

Sources: [QUICK_START.md:70-81](https://github.com/1cbyc/messagejs/blob/HEAD/QUICK_START.md#L70-L81), [packages/client/src/index.ts](https://github.com/1cbyc/messagejs/blob/HEAD/packages/client/src/index.ts)

Message Sending Flow

The sequence diagram below details the process of sending a message, from the client application to the API response.

This diagram shows the end-to-end flow for queuing a message via the SDK and API.

Sources: [packages/client/src/index.ts:98-124](https://github.com/1cbyc/messagejs/blob/HEAD/packages/client/src/index.ts#L98-L124), [packages/core/src/api/middleware/authMiddleware.ts:20-69](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/api/middleware/authMiddleware.ts#L20-L69), [packages/core/src/api/controllers/messageController.ts:22-72](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/api/controllers/messageController.ts#L22-L72), [API_REFERENCE.md:70-87](https://github.com/1cbyc/messagejs/blob/HEAD/API_REFERENCE.md#L70-L87)

API Reference

The system exposes a REST API for both the SDK and the dashboard.

Send Message Endpoint

• Endpoint: POST /api/v1/messages
• Authentication: Authorization: Bearer <api_key>
• Description: Queues a message to be sent.

Request Body (SendMessageRequest)

Field	Type	Required	Description
connectorId	string	Yes	ID of the connector to use.
templateId	string	Yes	ID of the template to use.
to	string	Yes	Recipient's identifier (e.g., phone number).
variables	Record<string, any>	Yes	Key-value pairs for template variables.
metadata	Record<string, any>	No	Optional metadata for logging.

Sources: [packages/core/src/types/apiTypes.ts:32-41](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/apiTypes.ts#L32-L41), [API_REFERENCE.md:70-87](https://github.com/1cbyc/messagejs/blob/HEAD/API_REFERENCE.md#L70-L87)

Success Response (202 Accepted)
On success, the API confirms that the message has been queued for processing.

Field	Type	Description
messageId	string	The unique ID of the created message log.
status	string	The initial status, which is always queued.
details	string	A human-readable confirmation message.

Sources: [packages/core/src/types/apiTypes.ts:47-54](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/types/apiTypes.ts#L47-L54), [packages/core/src/api/controllers/messageController.ts:55-61](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/src/api/controllers/messageController.ts#L55-L61)