Project Structure

Relevant source files

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

• mono-repo.md
• package.json
• packages/core/package.json
• packages/client/package.json
• packages/dashboard/package.json
• README.md
• packages/core/prisma/schema.prisma
• packages/client/src/index.ts

MessageJS is a monorepo that contains all the packages required to run the service, including the backend API, the client-facing SDK, and the user dashboard. This structure facilitates code sharing, particularly for TypeScript types, and simplifies dependency management and development workflows across the entire project. The project is managed using npm workspaces.

The high-level architecture follows a clear client-server model, where a lightweight client SDK communicates with a robust backend API. This API then routes requests to third-party messaging platforms.

Sources: README.md:16-20, package.json:6-8, mono-repo.md

Monorepo Architecture

The project is organized into a packages directory, which houses the individual, self-contained modules of the MessageJS ecosystem. This modular approach separates concerns between the backend, frontend SDK, and the management dashboard.

Sources: mono-repo.md:1-3, package.json:6-8

The following diagram illustrates the layout of the monorepo and its constituent packages.

Package Breakdown

The monorepo contains several key packages, each with a distinct role.

Package	Description	Source
@messagejs/core	The core backend API, built with Node.js and Express. It handles authentication, message processing, and database interactions.	[README.md:19](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L19), [packages/core/package.json:4](https://github.com/1cbyc/messagejs/blob/HEAD/packages/core/package.json#L4)
@messagejs/client	A lightweight frontend SDK for browsers and Node.js, enabling developers to send messages via the core API.	[README.md:20](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L20), [packages/client/package.json:4](https://github.com/1cbyc/messagejs/blob/HEAD/packages/client/package.json#L4)
@messagejs/dashboard	A React/Next.js application that provides a user interface for managing projects, API keys, and connectors.	[mono-repo.md:11](https://github.com/1cbyc/messagejs/blob/HEAD/mono-repo.md#L11), [packages/dashboard/package.json:4](https://github.com/1cbyc/messagejs/blob/HEAD/packages/dashboard/package.json#L4)
@messagejs/shared-types	A common package for sharing TypeScript types across other packages, ensuring consistency.	[README.md:21](https://github.com/1cbyc/messagejs/blob/HEAD/README.md#L21), [mono-repo.md:21](https://github.com/1cbyc/messagejs/blob/HEAD/mono-repo.md#L21)
docs	Contains the project documentation.	[mono-repo.md:14](https://github.com/1cbyc/messagejs/blob/HEAD/mono-repo.md#L14)
examples	Contains example applications and SDK demonstrations for platforms like React and Node.js.	[mono-repo.md:17](https://github.com/1cbyc/messagejs/blob/HEAD/mono-repo.md#L17)

High-Level System Flow

The system is designed to securely process message requests from a client application without exposing sensitive credentials. The flow begins with the client SDK, which sends a request to the API, and the API handles the secure communication with the third-party messaging service.

This diagram shows the general data flow for sending a message.

Database Schema

The backend (@messagejs/core) uses PostgreSQL as its database, with Prisma acting as the Object-Relational Mapper (ORM). The schema defines the core entities of the system: User, Project, Service (Connector), Template, and MessageLog.

Sources: packages/core/prisma/schema.prisma:7-11

The diagram below shows the relationships between the main database tables.

Database Enums

The schema enforces data integrity using enums for specific fields.

Enum	Values	Description
ServiceType	WHATSAPP, TELEGRAM, TWILIO_SMS	Defines the supported third-party messaging platforms.
MessageStatus	QUEUED, SENT, DELIVERED, FAILED, UNDELIVERED	Represents the lifecycle of a message as it is processed.

Sources: packages/core/prisma/schema.prisma:16-27

Scripts and Tooling

The project relies on npm workspaces to manage the monorepo. The root package.json contains scripts to run commands across all packages simultaneously.

Script	Description
build	Builds all packages in the workspace.
dev	Runs the development server for all packages.
test	Runs tests for all packages.
lint	Lints all packages.
typecheck	Runs TypeScript type checking across all packages.
core	Runs the development server for the @messagejs/core package specifically.
client	Runs the development build/watcher for the @messagejs/client package.
dashboard	Runs the development server for the @messagejs/dashboard package.

Sources: package.json:9-18