Contributing Guide

Relevant source files

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

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

This guide provides instructions for developers who wish to contribute to the MessageJS project. It covers setting up the development environment, understanding the project structure, and following the development workflow. The goal of MessageJS is to provide a simple, unified API for sending messages via multiple chat platforms like WhatsApp, Telegram, and SMS, without exposing credentials on the frontend.

The project is in an early development stage, with the core architecture and design completed. Current work is focused on implementing the backend API, database layer, and connectors.

Sources: README.md:11-14, README.md:68-71

Getting Started

Before you begin, ensure your development environment meets the following prerequisites.

Prerequisites

• Node.js: Version 20.0.0 or higher.
• npm: Version 10.0.0 or higher.

Sources: package.json:20-23

Installation

To set up the project locally, follow these steps:

1. Clone the repository:

   git clone https://github.com/messagejs/messagejs.git
   cd messagejs
   

2. Install dependencies:
   This command installs dependencies for all packages in the monorepo.

   npm install
   

3. Build all packages:
   This command compiles the TypeScript code for all workspaces.

   npm run build
   

Sources: README.md:29-38

Project Structure

MessageJS is a monorepo managed with npm workspaces. The packages are located in the packages/ directory.

Sources: package.json:8-10, mono-repo.md

Package Overview

The following diagram illustrates the high-level structure of the monorepo.

This diagram shows the main packages within the monorepo and their relationships.

Sources: mono-repo.md

The key packages are:

Package	Description
@messagejs/core	The Node.js/Express backend API that handles all logic.
@messagejs/client	The frontend SDK for browsers and Node.js environments.
@messagejs/dashboard	The React/Next.js dashboard for managing projects.
@messagejs/shared-types	Shared TypeScript types used across packages.
@messagejs/docs	Project documentation.
@messagejs/examples	Example applications demonstrating SDK usage.

Sources: README.md:18-24, mono-repo.md

Development Workflow

Common Scripts

The root package.json contains scripts to manage the entire monorepo.

Script	Description
npm run build	Builds all packages in the workspaces.
npm run dev	Runs all packages in development/watch mode.
npm run test	Runs tests for all packages.
npm run lint	Lints all packages.
npm run typecheck	Runs TypeScript type checking across all packages.
npm run core	Starts the @messagejs/core backend in development mode.
npm run client	Builds and watches the @messagejs/client SDK.
npm run dashboard	Starts the @messagejs/dashboard in development mode.

Sources: package.json:11-19

Contribution Process

Contributions are welcome. Please follow this process:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

Sources: README.md:80-86

The following flowchart illustrates the contribution workflow.

Backend Architecture (@messagejs/core)

The @messagejs/core package is an Express.js application written in TypeScript. It serves as the main API for the client SDK and the dashboard.

Sources: packages/core/package.json:4, packages/core/src/index.ts

Database Schema

The backend uses PostgreSQL with Prisma as the ORM. The schema defines the core data models for the application.

Sources: packages/core/prisma/schema.prisma:8-12

The entity-relationship diagram below shows the database structure.

This diagram illustrates the relationships between users, projects, services (connectors), templates, and message logs.

Sources: packages/core/prisma/schema.prisma:30-103

API Request Flow

The main entry point for the core server is packages/core/src/index.ts. It initializes the Express app, applies global middleware like express.json(), and mounts the API routers.

A typical request to send a message (POST /api/v1/messages) follows this sequence:

1. The request hits the Express server.
2. The validateApiKey middleware verifies the Authorization: Bearer <api_key> header.
3. If the key is valid, the middleware attaches API key details to the req object and passes control to the controller.
4. The sendMessage controller in messageController.ts processes the request, validates input, and queues the message for sending.
5. A 202 Accepted response is sent back to the client, indicating the message has been queued.

Sources: packages/core/src/index.ts, packages/core/src/api/middleware/authMiddleware.ts, packages/core/src/api/controllers/messageController.ts

The sequence diagram below visualizes the sendMessage flow.

Connector Interface

The backend features a pluggable connector system to support various messaging platforms. Every connector must implement the IConnector interface.

Sources: packages/core/src/connectors/IConnector.ts

// packages/core/src/connectors/IConnector.ts

export interface IConnector {
  readonly type: ConnectorType;
  readonly name: string;
  validate(): Promise<ConnectorStatus>;
  sendMessage(options: SendOptions): Promise<SendResult>;
  getStatus?(externalId: string): Promise<MessageStatus>;
}

Sources: packages/core/src/connectors/IConnector.ts:70-93

The diagram below shows the IConnector interface and a conceptual implementation.

This diagram shows that concrete classes like WhatsAppConnector must implement the methods defined in the IConnector interface.

Sources: packages/core/src/connectors/IConnector.ts

Frontend Architecture (@messagejs/client)

The @messagejs/client package provides a lightweight SDK for interacting with the MessageJS API from a browser or Node.js application. It is designed to be simple, similar to EmailJS.

Sources: README.md:11-14, packages/client/src/index.ts

SDK Usage

The SDK exports a singleton instance named messagejs. It must be initialized before use.

1. Initialization: Call messagejs.init() with your API key and project ID.
2. Sending a Message: Call messagejs.sendMessage() with the recipient, message content, and connector details.

Sources: QUICK_START.md:73-84, QUICK_START.md:100-113, packages/client/src/index.ts:76-90, packages/client/src/index.ts:97-130

The MessageJS class provides the core functionality.

This diagram shows the private properties and public methods of the main SDK class.

Sources: packages/client/src/index.ts:69-131

Summary

This guide provides the foundational knowledge needed to contribute to MessageJS. Contributors should familiarize themselves with the monorepo structure, development scripts, and the core backend/frontend architecture. By following the outlined contribution process and understanding the key components like the database schema and connector interface, you can effectively add new features and fix issues.