Operational

Operational is an open-source event tracking platform that delivers real-time push notifications to mobile and desktop whenever critical product events occur — signups, webhook failures, cronjob errors, billing events, or anything else that demands immediate attention. Unlike general analytics tools, Operational is purpose-built for operational visibility: you see events as they happen, respond through built-in action buttons, and understand complex workflows through chained event contexts.

The platform is structured as a monorepo combining a Vue 3 SPA, an Express 5 backend, a shared npm SDK, and a WordPress plugin — all deployable as a single Docker image. MySQL 8 stores events and workspace data, with optional ClickHouse for advanced analytics at scale. Self-hosters get full parity with the hosted service, including VAPID-based web push, multi-project support, teammate invites, and a dashboard widget system.

Operational is positioned as an open-source alternative to tools like Logsnag, aimed at technical founders who want instant operational awareness without the overhead of a full observability stack. Integration takes minutes through the official SDK, REST API, or the built-in playground that generates copy-paste code in Node.js, PHP, Python, and Rust.

What You Get

• VAPID Web Push Notifications - Receive real-time push alerts on mobile and desktop browsers via the Web Push protocol whenever a critical event fires, with no native app required — configurable per event with notify and test toggles.
• Action Buttons with Webhook Triggers - Attach custom buttons (e.g., ‘Ban IP’, ‘Approve User’, ‘Retry Job’) directly to event cards that POST to any external webhook URL, enabling one-click operational responses from inside the event feed.
• Event Contexts (Events-in-Events) - Group related events into named contexts using a contextStart/contextId pattern so you can trace multi-step workflows like a signup flow, payment lifecycle, or batch job as a single linked chain.
• Structured JSON Event Rendering - Send raw JSON payloads from webhooks or APIs and have them rendered with syntax highlighting and structured formatting — useful for inspecting Stripe payloads, GitHub events, or internal log objects.
• Dashboard Widget System - Build composable metric dashboards from a schema-driven widget engine with TTL-cached data pipelines, supporting event-count charts, time-series views, and custom data sources.
• Multi-Project and Teammate Support - Create multiple isolated workspaces for different products or clients, invite teammates with email-based flows, and manage API keys per project — added in v0.3.0.
• Progressive Web App (PWA) - Install Operational as a PWA on any mobile homescreen and receive push notifications just like a native app, using service workers managed through vite-plugin-pwa.
• Multi-Language SDK and Playground - Integrate via the official @operational.co/sdk npm package or the REST API, with a built-in playground that generates copy-paste code examples in Node.js, PHP, Python, and Rust.

Common Use Cases

• SaaS signup monitoring - A founder wires Operational into their registration endpoint to receive an instant push notification whenever someone signs up, with user email and plan details visible in the event feed for immediate personal follow-up.
• Cronjob failure alerting - A backend engineer sends a heartbeat event at the end of every scheduled job; if the next heartbeat is missing, Operational fires an alert so the team knows before users notice the outage.
• Stripe webhook inspection - A product team pipes all Stripe payment events into Operational to capture the full JSON payload, view charge details with syntax highlighting, and trigger a ‘Refund’ action button without switching to the Stripe dashboard.
• Suspicious login auditing - A security-conscious team logs every failed authentication attempt and unusual login location as an Operational event, grouping them into a context per user session to trace attack patterns.
• Multi-client agency monitoring - An agency running multiple client apps creates a separate Operational workspace per client, routes events from each backend, and grants client teammates read access so everyone sees only their project.

Under The Hood

Architecture Operational follows a monorepo-driven, service-oriented architecture where a central Express 5 API acts as the coordination hub for a set of specialized service classes — ingestion, webpush, billing, cron, storage, session, and database — each initialized in a coordinated parallel startup sequence. Route components encapsulate controller logic directly within their handlers rather than through a strict controller/service separation, creating a pragmatic but somewhat flat structure. The Vue 3 SPA communicates with the backend over a REST interface managed through Pinia stores with a thin API abstraction layer. The widget and dashboard subsystem introduces a data-fetching layer with TTL-backed caching keyed on workspace/widget/schema tuples, showing deliberate performance thinking. Self-hosted mode versus hosted mode is gated via a config flag that conditionally enables routes and billing features, allowing a single codebase to serve both deployment targets.

Tech Stack The backend runs on Node.js 18+ with Express 5 and uses Prisma as a type-safe ORM against MySQL 8, with optional ClickHouse integration for advanced event analytics. Web Push notifications are delivered via the VAPID protocol using the web-push library, with credentials managed through environment configuration. Email delivery supports both SMTP and Resend as providers, and billing is handled through Stripe. The frontend is a Vue 3 SPA using Pinia for reactive state, vue-router for navigation, and Vite for bundling with PWA support via vite-plugin-pwa. The marketing and documentation site is built in Astro with Vue islands. Shared packages distribute UI components in a SCSS-based design system, utility libraries, a published npm SDK, and a WordPress plugin — all coordinated through npm workspaces with Docker images published to GHCR for production deployment.

Code Quality No automated test suite exists across the codebase — no unit tests, integration tests, or test runners are configured in the app or backend. Validation middleware contains a logic gap where Fastest Validator error arrays are treated as passing the validation check rather than failing it. Error handling is generic, relying on broad try/catch blocks that log to console and return status 400 without structured error types or recovery paths. The codebase mixes Options API and Composition API Vue patterns, and commented-out code with deprecated notices appears in the backend entry point. Type safety is limited since the frontend is plain JavaScript without TypeScript. Prettier is configured for formatting consistency, which provides a baseline of code clarity.

What Makes It Unique The core differentiator is treating push notifications as a first-class operational primitive — events trigger VAPID web push directly to mobile and desktop without requiring any native app install. The action button system, where event cards carry webhook-triggering buttons that execute arbitrary HTTP calls from within the event viewer, is uncommon in open-source event trackers. Event contexts allow chaining related events into a workflow audit trail, providing lightweight tracing without a full distributed tracing system. The schema-driven dashboard widget engine with TTL caching enables composable metric views against ingested event data. A multi-language SDK surface covering JavaScript, PHP, Python, and Rust, combined with a built-in playground UI for live code generation, significantly lowers integration friction for diverse tech stacks.

Self-Hosting

Operational is released under the GNU Affero General Public License v3.0 (AGPL-3.0). This is a strong copyleft license that allows commercial use, modification, and distribution, but with a critical condition: if you deploy a modified version and make it accessible over a network, you must release the modified source code under the same license. For teams self-hosting internally without exposing it as a service to the public, this is generally unproblematic. Teams building a commercial product on top of Operational and offering it as a SaaS to others should consult legal counsel before doing so.

Running Operational yourself requires a Linux host with Docker and Docker Compose, a MySQL 8 database, and Node.js 18 or higher if building outside Docker. The Docker Compose setup bundles the backend API, Vue SPA via nginx, and a MySQL container into a single stack, making initial deployment straightforward on a VPS, Render, or any container platform. You are responsible for database backups, SSL termination, uptime, and applying upstream updates by pulling new Docker images tagged to release versions. Push notifications require you to generate your own VAPID key pair and configure email sending through SMTP or Resend for teammate invitations, which adds a few environment variables to manage. Scaling beyond a single node is not supported by the provided Docker setup.

The hosted service at operational.co handles all of this for you, including SSL, uptime, backups, and seamless upgrades. The hosted tier adds usage-based billing through Stripe and potentially higher event retention and throughput limits that are not clearly bounded in the self-hosted version. The trade-off is the usual one: self-hosting gives you full data ownership and no per-seat fees at the cost of operational responsibility; the hosted service trades those concerns away for a subscription. The project’s Discord community provides support for both paths, though response times and SLA commitments are informal.