Beacon

Beacon is a high-performance, multi-channel notification engine designed for complex enterprise environments. It provides smart routing, robust rate limiting, and dynamic configuration management for Slack, Email, and SMS notifications.

🚀 Key Features

🛡️ Advanced Rate Limiting

• Multi-Level Hierarchy: Limits can be strictly enforced at three levels:
  1. EventType (e.g., error_event)
  2. EventName (e.g., DatabaseConnectionError)
  3. SourceEntity (e.g., customer-org-123 - most granular)
• State Consistency: Implements a hybrid Redis + Postgres architecture.
  • High-speed decisions via Redis pipelines (nanosecond latency).
  • Auto-Hydration: On restart or cache eviction, Redis counters are automatically synced from persistent Postgres audit logs to prevent limit resets.
• Fail-Open Design: Ensures critical alerts are never blocked due to infrastructure hiccups.

⚙️ Dynamic Configuration Engine

• Hot Reloading: Rules are loaded from the database and cached. Updates to routing rules apply instantly without service restarts.
• Circuit Breaker: Protects the database from query storms during outages.
• Smart Routing:
  • VIP Client Routing: Route all alerts for a specific client to a dedicated channel.
  • Partial Matching: Fallback logic handles undefined events gracefully.

📢 Multi-Channel Support

• Slack: Full support for webhooks, user tagging, and rich formatting.
• Email & SMS: Extensible provider interface ready for integration (scaffolding in place).

---

🛠️ Architecture

Beacon is built as a modular Go service with a clean separation of concerns:

• Core Service: Handles API requests, config resolution, and dispatch logic.
• Worker Pool: Uses Asynq (Redis-backed queue) for reliable background task processing.
• Storage Layer:
  • PostgreSQL: Durable storage for configuration, audit logs, and event history.
  • Redis: High-speed cache for rate limiting counters and config caching.
• Frontend: A React/Vite dashboard for managing configurations and viewing system status.

---

⚡ Quick Start

Prerequisites

• Docker & Docker Compose
• Go 1.22+ (for local development)
• Node.js 18+ (for frontend development)

Running with Docker

1. Clone the repository

   git clone https://github.com/your-org/beacon.git
   cd beacon

2. Configure Environment Copy the example environment file:

   cp .env.example .env

3. Start Services

   docker-compose up -d --build

   The API will be available at http://localhost:8080.

Local Development

1. Start Dependencies (Postgres & Redis)

   docker-compose up -d postgres redis

2. Run Backend

   make run

3. Run Frontend

   cd web
   npm install
   npm run dev

---

📚 API Documentation

POST /api/v1/notify

Send a notification event.

Payload:

{
  "event_type": "error_event",
  "event_name": "DatabaseTimeout",
  "source_entity_id": "tenant-456",
  "payload": {
    "message": "Connection timed out after 5000ms",
    "details": "..."
  }
}

GET /api/configs

Retrieve active routing configurations.

---

🧪 Testing

Run the full test suite:

make test

🤝 Contributing

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

---

📄 License

Distributed under the MIT License. See LICENSE for more information.