simplens-core

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #go #machine-learning #rust #linux #docker #nodejs #java #vue #mcp #openai #open-source

(★ 11)

Open-source plugin-based notification orchestration engine for developers who value control

simplens-core Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Scalable. Reliable. Extensible

<h3 align="center">Open-source plugin-based notification orchestration engine for developers who value control</h3>

<a href="#key-features">Features</a> •
 <a href="#architecture">Architecture</a> •
 <a href="#quick-start">Quick Start</a> •
 <a href="#admin-dashboard">Dashboard</a> •
 <a href="https://simplens.in">Website</a> •
 <a href="https://simplens.in/docs/core">Documentation</a>

---

**SimpleNS** is a self-hosted notification orchestration engine that manages delivery workflows—retries, scheduling, crash recovery, and scaling—while delegating the actual sending to **plugins**. Build your own providers or use community plugins to support any channel: Email, SMS, WhatsApp, Push, and beyond.

---

## Why SimpleNS?

| ❌ The Problem | ✅ How SimpleNS Solves It |
|----------------|---------------------------|
| Locked into a single notification provider | **Plugin architecture** — swap providers without code changes |
| Notifications fail silently | **Exponential backoff retries** with configurable limits |
| Crashes leave messages stuck | **Crash recovery service** detects & rescues orphaned notifications |
| Single point of failure | **Horizontally scalable** workers and processors |
| Complex scheduling logic | **Built-in scheduled delivery** with Redis-backed queues |
| Different APIs for each channel | **Unified API** for all notification channels |

---

## Key Features

- 🔌 **Plugin-Based Delivery** — Delegate sending to any provider plugin
- 🔄 **Exponential Backoff Retries** — Automatic retry with increasing delays
- 🛡️ **Crash Recovery** — Detect and rescue orphaned notifications
- ⏰ **Scheduled Delivery** — Queue notifications for future delivery
- 📈 **Horizontal Scaling** — Scale processors independently per channel
- 📡 **Multi-Channel Support** — Email, WhatsApp, SMS, Push via plugins
- 🚦 **Rate Limiting** — Per-provider token bucket algorithm
- 🔔 **Webhook Callbacks** — Real-time delivery status updates
- 📊 **Admin Dashboard** — Monitor, search, and retry notifications
- 🔔 **Admin Alert Channels** — Receive system health alerts via Discord, Telegram, and more
- 📝 **Notification Templates** — Create, edit, and manage reusable notification templates with live preview
- 🤖 **MCP Server** — Native Model Context Protocol server for AI agent integration
- 📋 **Observability** — Centralized logging with Grafana + Loki

---

## AI Agent Integration (MCP)

SimpleNS includes a native [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server (`@simplens/mcp`) that allows AI assistants like Github Copilot (VS code), Antigravity and OpenAI Codex to interact directly with your notification infrastructure.

AI agents can securely connect to your SimpleNS instance to:
- **Send Notifications** — Dispatch individual or batch notifications using templates or inline content
- **Explore Schemas** — Dynamically discover available channels, providers, and required payload fields
- **Monitor Health** — Check system alerts and investigate failed deliveries
- **Retry Failed Events** — Programmatically identify and retry failed notification events

### Running the MCP Server
Start the server without installation:
```bash
# Run in streamable-http mode
npx -y @simplens/mcp

# Run in stdio mode
npx -y @simlpens/mcp --stdio
```
*(Supports both `streamable-http` and `stdio` transports)*

---

## Architecture

![SimpleNS Architecture](https://raw.githubusercontent.com/SimpleNotificationSystem/simplens-core/master/assets/SimpleNS-HLD.png)

| Component | Description |
|-----------|-------------|
| **API Server** | REST API for notification ingestion (`/api/notification`, `/api/notification/batch`) |
| **Background Worker** | Polls outbox, publishes to Kafka, consumes status updates |
| **Unified Processor** | Plugin-based notification delivery with rate limiting |
| **Delayed Processor** | Handles scheduled notifications via Redis ZSET queue |
| **Recovery Service** | Detects stuck notifications and reschedules them |

### Plugin System

SimpleNS Core handles **orchestration**; plugins handle **delivery**.

Plugins are automatically installed at runtime based on your `simplens.config.yaml` configuration. Use the **Config Generator CLI** to create or update your config:

```bash
# Generate config for a plugin
npx @simplens/config-gen generate @simplens/mock

# Generate config for multiple plugins
npx @simplens/config-gen gen @simplens/nodemailer-gmail @simplens/twilio-sms

# Add a plugin to existing config
npx @simplens/config-gen gen @simplens/nodemailer-gmail -c simplens.config.yaml

# List available official plugins
npx @simplens/config-gen list --offical

#List available community plugins
npx @simplens/config-gen list --community
```

#### Building Custom Plugins

The `@simplens/create-simplens-plugin` CLI scaffolds a plugin project:

```bash
npx @simplens/create-simplens-plugin
```

This generates the boilerplate so you only write the delivery logic:

```typescript
import { SimpleNSProvider, ProviderManifest } from '@simplens/sdk';

class MyProvider implements SimpleNSProvider {
  readonly manifest: ProviderManifest = {
    name: 'my-provider',
    channel: 'email',
    requiredCredentials: ['API_KEY'],
    // ...
  };
  
  async send(notification) {
    // Your delivery logic
    return { success: true, messageId: 'msg-123' };
  }
}
```

---

## Quick Start

### Prerequisites

- **Docker** and **Docker Compose**

### Installation

Get SimpleNS running in under a minute with a single command:

**Linux:**
```bash
curl -fsSL https://simplens.in/api/install/linux | bash
```

**Windows (PowerShell as Administrator):**
```powershell
irm https://simplens.in/api/install/windows | iex
```

**npm:**
```bash
npx @simplens/onboard
```

The installer will automatically pull Docker images, configure your environment, set up plugin configuration, and start all services.

### Verify Installation

```bash
curl http://localhost:3000/health
```

Expected response:
```json
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### Send Your First Notification

**Using the Dashboard (recommended):**

1. Open [http://localhost:3002](http://localhost:3002)
2. Login with your configured credentials (default: `admin` / `<your-password-from-env>`)
3. Navigate to **Send**, select a channel/provider, fill in the fields, and click **Send Notification**

**Using cURL:**

```bash
curl -X POST http://localhost:3000/api/notification \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer <YOUR-NS-API-KEY>" \
 -d '{
 "request_id": "550e8400-e29b-41d4-a716-446655440000",
 "client_id": "55283667-1f58-467d-86a1-47f7f0e059f2",
 "channel": ["mock"],
 "recipient": {
 "user_id": "user123"
 },
 "content": {
 "mock": {
 "message": "Hello from SimpleNS!"
 }
 }
 }'
```

> **Tip:** Each provider's recipient and content schemas can vary. Use the **Payload Studio** in the admin dashboard to get the exact schema.

### Check Notification Status

1. Go to **Events** page in the dashboard
2. Search for your notification by ID
3. Check status: `pending` → `processing` → `delivered`

### Accessing Services

| Service | URL | Description |
|---------|-----|-------------|
| API Server | [http://localhost:3000](http://localhost:3000) | Notification API |
| Admin Dashboard | [http://localhost:3002](http://localhost:3002) | Monitoring & management |
| Grafana | [http://localhost:3001](http://localhost:3001) | Log visualization |
| Kafka UI | [http://localhost:8080](http://localhost:8080) | Kafka topic monitoring |

### Add More Plugins

```bash
# Add Gmail email provider
npx @simplens/config-gen generate @simplens/nodemailer-gmail -c simplens.config.yaml

# List available plugins
npx @simplens/config-gen list --official
```

> For production deployments, see the [Self-Hosting Guide](https://simplens.in/docs/core/self-hosting) which covers distributed deployments, cloud infrastructure integration, and security hardening.

---

## Admin Dashboard

![Admin Dashboard](https://raw.githubusercontent.com/SimpleNotificationSystem/simplens-core/master/assets/DashboardUI.png)

The Admin Dashboard provides a modern interface for monitoring and managing notifications:

- 🏠 **Dashboard Home** — Overview with status cards showing total, delivered, pending, and failed counts
- 📡 **Channel Cards** — Visual cards for each configured channel (Email, WhatsApp, etc.) with quick navigation
- 📋 **Events Explorer** — Paginated event table with filtering, search, and status indicators
- 🔴 **Failed Events** — Dedicated view for failed notifications with retry capabilities
- 🚨 **Alerts** — System alerts for orphaned notifications and recovery events requiring attention
- 📈 **Analytics** — Charts and visualizations for notification status and channel distribution
- 🔌 **Plugins** — View installed plugins, their channels, and provider configurations
- 🔧 **Payload Studio** — Interactive schema explorer for building and notification payloads
- 🔔 **Admin Alert Channels** — Configure external channels (Discord, Telegram, etc.) to receive system alerts
- 📝 **Notification Templates** — Create, manage, and preview reusable notification templates

---

## License

MIT License — see [LICENSE](./LICENSE) for details.

---

Built with ❤️ for developers who need reliable notifications

simplens-core

simplens-core Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

simplens-core

simplens-core Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README