Backend Configuration

Relevant source files

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

• docker-compose.yml
• packages/core/src/index.ts
• packages/core/prisma/schema.prisma
• packages/core/package.json
• packages/core/src/api/middleware/authMiddleware.ts
• packages/core/src/types/dataModels.ts
• package.json

The backend for MessageJS, contained within the @messagejs/core package, is a Node.js application built with Express. Its configuration encompasses the server environment, database setup, data modeling, and API routing. The system is designed to be run in a containerized development environment using Docker and relies on environment variables for critical settings like database connections and server ports.

The core of the backend configuration is managed through several key files: packages/core/src/index.ts for the application entry point, docker-compose.yml for the development environment services, and packages/core/prisma/schema.prisma for defining the database structure. Authentication and data models are further defined in authMiddleware.ts and dataModels.ts respectively.

Core Application Setup

The backend is an Express.js server initialized in packages/core/src/index.ts. This file serves as the main entry point for the application.

Sources: packages/core/src/index.ts

Server Initialization

The server setup involves:

1. Loading environment variables from a .env file using the dotenv library.
2. Creating an Express application instance.
3. Defining the server port, which defaults to 3001 if not specified in the environment variables.
4. Applying global middleware, such as express.json() to parse JSON request bodies.
5. Mounting API routers.
6. Starting the HTTP server to listen for incoming connections.

Sources: packages/core/src/index.ts:10-16, 21-22, 37-41

The following diagram illustrates the server startup sequence.

Health Check

A public health check endpoint is configured at the root path (/) to confirm that the API is running. It responds with a 200 OK status and a welcome message.

// packages/core/src/index.ts:27-32
app.get('/', (req: Request, res: Response) => {
  res.status(200).json({
    status: 'ok',
    message: 'Welcome to the MessageJS Core API!',
  });
});

Sources: packages/core/src/index.ts:27-32

Development Environment

The development environment relies on Docker to provide a consistent PostgreSQL database instance. The configuration is defined in the root docker-compose.yml file.

Sources: docker-compose.yml

Database Service

A service named postgres is defined to run a PostgreSQL 15 database in a Docker container.

# docker-compose.yml:15-38
services:
  postgres:
    image: postgres:15-alpine
    container_name: messagejs_postgres_dev
    environment:
      POSTGRES_USER: messagejs
      POSTGRES_PASSWORD: password
      POSTGRES_DB: messagejs_dev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: always

Sources: docker-compose.yml:15-38

The configuration uses a named volume postgres_data to persist database data across container restarts. The database is exposed on the host machine at port 5432.

Sources: docker-compose.yml:32-36, 41-43

Environment Variables

The postgres service is configured using the following environment variables. These must match the DATABASE_URL in the .env file used by the core application.

Variable	Value	Description
POSTGRES_USER	messagejs	The username for the database.
POSTGRES_PASSWORD	password	The password for the database user.
POSTGRES_DB	messagejs_dev	The name of the database to create.

Sources: docker-compose.yml:23-25

Database Schema

The database schema is defined and managed using Prisma. The schema file specifies the data source, generator, and data models.

Sources: packages/core/prisma/schema.prisma

Data Models

The schema defines five primary models: User, Project, Service, Template, and MessageLog. These models map to tables in the PostgreSQL database.

The following ER diagram shows the relationships between the data models.

Enums

The schema defines two enums, ServiceType and MessageStatus, to enforce data integrity for specific fields.

ServiceType

Value	Description
WHATSAPP	WhatsApp messaging service.
TELEGRAM	Telegram messaging service.
TWILIO_SMS	Twilio SMS service.

Sources: packages/core/prisma/schema.prisma:19-23

MessageStatus

Value	Description
QUEUED	Message accepted by the API, not yet sent.
SENT	Message sent to the third-party provider.
DELIVERED	Delivery confirmation received.
FAILED	Message failed to send.
UNDELIVERED	Provider confirmed message could not be delivered.

Sources: packages/core/prisma/schema.prisma:25-31

API Configuration

Routing

API routes are defined in separate router files and mounted in index.ts. The primary message-related routes are handled by messageRouter, which is mounted under the /api/v1/messages path.

// packages/core/src/index.ts:35
app.use('/api/v1/messages', messageRouter);

Sources: packages/core/src/index.ts:35

Authentication Middleware

API routes are protected by middleware that validates credentials. The validateApiKey middleware is responsible for authenticating requests made from the client SDK.

Sources: packages/core/src/api/middleware/authMiddleware.ts

The middleware checks for an Authorization header with a Bearer token. It then validates the API key. In the current implementation, it uses a mock API key for validation.

The following sequence diagram shows the API key validation flow.

If validation is successful, the middleware attaches an apiKey object containing the id and projectId to the Express Request object for use in downstream controllers.

Sources: packages/core/src/api/middleware/authMiddleware.ts:54-57, packages/core/src/types/security.ts:16-19

Dependencies and Scripts

The backend's dependencies and operational scripts are defined in packages/core/package.json.

Key Dependencies

Package	Description
express	Web framework for Node.js.
dotenv	Loads environment variables from a .env file.
@prisma/client	Auto-generated Prisma client for database access.
cors	Middleware to enable Cross-Origin Resource Sharing.
tsx	TypeScript execution and watching for development.

Sources: packages/core/package.json:17-21, 26-28

Scripts

The following scripts are used to manage the backend lifecycle:

Script	Command	Description
dev	tsx watch src/index.ts	Starts the server in development mode with hot-reloading.
build	tsc	Compiles the TypeScript source code to JavaScript in the dist directory.
start	node dist/index.js	Runs the compiled JavaScript application.

Sources: packages/core/package.json:10-12 The monorepo root package.json provides a convenience script npm run core to execute the dev script within the @messagejs/core workspace. Sources: package.json:12