Pendulum Core

The core backend services for Pendulum BaaS - a self-hosted, reactive Backend as a Service platform.

Pendulum is a complete backend solution that provides instant real-time synchronization across all connected clients. Built for developers who want to focus on building features, not managing backend infrastructure.

Key Benefits:

• Self-hosted - Deploy to your own AWS account, keep your data
• Real-time by default - All database changes automatically sync to connected clients
• Zero configuration - Collections created automatically, no schemas required
• Familiar REST APIs - Standard HTTP endpoints, no proprietary query languages
• Complete solution - Backend services, admin dashboard, CLI, and SDK included

Overview

Pendulum Core provides the essential backend infrastructure with real-time capabilties including:

• App Service - RESTful API for CRUD operations, authentication, and authorization
• Events Service - Real-time event broadcasting via Server-Sent Events (SSE)
• Admin Dashboard - Web-based management interface
• MongoDB Integration - Document database with automatic real-time updates

Quick Start

Prerequisites

• Node.js 18+
• Docker and Docker Compose

Installation & Setup

1. Install Pendulum Core:

   npm install @pendulum-baas/core

2. Start the complete backend environment:

   npx pendulum dev

   This automatically starts:

   • MongoDB on port 27017
   • App Service on port 3000
   • Events Service on port 8080
   • Admin Dashboard at http://localhost:3000/admin

3. Configure environment (optional):

   # .env file
   DB_NAME=your_app_name
   JWT_SECRET=your_jwt_secret_key
   # Other settings use sensible defaults

Database Operations

Collections are created automatically on first access with smart defaults:

• Document tracking - Automatic userId, createdBy, updatedBy fields on all documents
• Role-based permissions - admin, user, public roles with configurable CRUD controls
• Flexible access control - Default open permissions, customizable per collection via admin dashboard
• Real-time updates - All database changes automatically broadcast to subscribed clients

API Endpoints

CRUD Operations:

GET    /pendulum/api?collection=<name>         # Get all documents
GET    /pendulum/api/<id>?collection=<name>    # Get single document  
POST   /pendulum/api?collection=<name>         # Insert documents
PATCH  /pendulum/api/<id>?collection=<name>    # Update document
DELETE /pendulum/api/<id>?collection=<name>    # Delete document

Authentication

POST /pendulum/auth/register # User registration
POST /pendulum/auth/login    # User login
GET  /pendulum/auth/me       # Get current user

Real-time Events

GET /pendulum-events/events  # SSE connection for live updates

Admin Dashboard

GET /admin         # Admin dashboard interface
GET /pendulum/logs # Server logs via SSE

Additional Features

• Bulk operations (/some endpoints for batch insert/update/delete)
• Pagination support (limit, offset, sortKey query parameters)
• Collection permissions management (/pendulum/permissions)

📖 More Details: See the SDK README for client integration examples and the CLI README for deployment options.

Docker Services

# compose.yaml includes:
mongodb:     # MongoDB database
app:         # Main API service  
events:      # Real-time events service

Management Commands

docker compose up    # Start all services
docker compose logs  # View service logs
docker compose stop  # Stop services

Production Deployment

For production, use the Pendulum CLI which automatically provisions AWS infrastructure:

pendulum deploy    # Deploy to AWS (ECS, DocumentDB, ALB)
pendulum destroy   # Remove all AWS resources

Admin Dashboard

Access the admin interface at http://localhost:3000/admin to:

• View real-time database operations
• Manage user permissions
• Configure collection access controls
• Monitor system logs

Dependencies Downloaded with npm install

• Express.js - Web framework
• MongoDB - Document database
• JWT - Authentication tokens
• bcrypt - Password hashing
• Morgan - HTTP logging
• CORS - Cross-origin support