Aurora

Software suite for DMX lighting, narrowcasting, and music integration

---

Overview

Aurora is the software suite that integrates and synchronizes DMX lighting, narrowcasting screens, and currently playing music — developed by and for Study Association GEWIS.

The system is built around a publish-subscribe architecture. The core serves as the central hub: it receives commands and state changes, and pushes them in real time to all connected subscribers over SocketIO WebSockets. End users control Aurora through the backoffice web interface, which communicates with the core over HTTP.

Architecture

┌─────────────┐  HTTP   ┌──────────────┐  SocketIO    ┌─────────────────────┐
│  Backoffice │ ──────▶ │              │ ──────────▶  │ Narrowcasting Screen│
│  (web UI)   │         │  Aurora Core │              └─────────────────────┘
└─────────────┘         │              │  SocketIO    ┌─────────────────────┐
                        │  (publisher) │ ──────────▶  │  Audio Player       │
┌─────────────┐  HTTP   │              │              └─────────────────────┘
│ Beat        │ ──────▶ │              │  SocketIO    ┌─────────────────────┐
│ Detector    │         │              │ ──────────▶  │  DMX Lights Proxy   │
└─────────────┘         └──────────────┘              └─────────────────────┘
                                │
                             SocketIO
                                │
                        ┌───────▼────────┐
                        │ Lights         │
                        │ Simulator      │
                        └────────────────┘

All subscribers authenticate with an API key, then maintain a persistent SocketIO connection to receive real-time commands. Subscribers may additionally fetch data from the core over HTTP as needed.

Repositories

Repository	Role	Tech
aurora-core (this repo)	Central publisher — receives commands and pushes state to all subscribers	TypeScript, NodeJS, SocketIO
aurora-backoffice (this repo)	Web management UI for humans to control Aurora	TypeScript, Vue, PrimeVue
aurora-client (this repo)	Narrowcasting screen client — displays posters and information on screens	TypeScript, NodeJS, SocketIO
aurora-audio-player	Audio subscriber — plays music as commanded by the core	TypeScript, NodeJS
aurora-lights-proxy	DMX controller bridge — forwards DMX packets from core to ArtNet hardware	Python, Art-Net
aurora-lights-simulator	Lights effect development tool — simulate DMX output without physical hardware	TypeScript, NodeJS
aurora-beat-detector	Real-time beat detection — sends beat events to core so lights sync to music automatically	TypeScript, NodeJS

Prerequisites

• Node.js 22+ — Download
• pnpm — Install (enabled via corepack enable on Node.js 16.13+)
• Git — Download

Quick Start

This repository contains the Aurora Core. For development setup of the core itself, see apps/aurora-core/README.md.

# Clone the repository
git clone https://github.com/GEWIS/aurora-core.git
cd aurora-core

# Install all dependencies (monorepo)
pnpm install

# Set up environment
cp apps/aurora-core/.env.example apps/aurora-core/.env

# Start developing
cd apps/aurora-core && pnpm dev

Development with Docker Compose

The monorepo includes a one-command Docker Compose setup that runs the core, backoffice, client (narrowcasting), and their dependencies together.

Prerequisites

• Docker with Compose V2 (included in Docker Desktop / Docker Engine 25+)
• Node.js 22+ with pnpm (for the dev scripts only)

Quick start

# Start everything
pnpm dev

This will:

1. Start the core (http://localhost:3000) with a pre-seeded SQLite database (GEWIS data set)
2. Start the backoffice (http://localhost:8080)
3. Start the client (http://localhost:8081) with Vite dev server proxying API calls to the core
4. Wait for the core to be ready and the database seeded
5. Extract the first screen's API key from the database
6. Open the client, backoffice, and API docs in your browser
7. Stay running in the foreground — press Ctrl-C to stop the environment gracefully

Teardown

docker compose down

Containers are removed but the node_modules volume is kept for fast restarts. To fully reset:

docker compose down -v    # also removes cached node_modules

External Integrations

Aurora Core integrates with several external services for extended functionality:

Service	Purpose	Required Env
Spotify	Currently playing track display	SPOTIFY_*
Trello	Poster content management for narrowcasting	TRELLO_*
NS	Train departure information on narrowcasting posters	NS_API_KEY
SudoSOS	Borrel (event) poster generation	SUDOSOS_API_URL

Integration API

If you want to integrate your own service with Aurora — to fetch data, send commands, or build a custom subscriber — see the Integrations README in the core for detailed documentation on authentication and the available endpoints.

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feat/your-feature-name.
3. Make your changes.
4. Run tests: pnpm --filter @gewis/aurora-core test.
5. Run linting: pnpm lint.
6. Commit using Conventional Commits: git commit -m "feat: add your feature".
7. Push: git push origin feat/your-feature-name.
8. Open a Pull Request.

License

Copyright © 2023-2025 Study Association GEWIS — Some rights reserved.

Aurora is licensed under the GNU Affero General Public License v3.0 or later. See the LICENSE file for details.