OpsCord

The evidence-based incident response platform with deterministic candidate ranking.
Turn scattered telemetry and deployments into a clear picture of incident causality.

Features • Architecture • Quick Start • Deployment • API

OpsCord’s deterministic candidate ranking tracing incident causality in real-time.

---

✨ Features

Incident response is often chaotic, manual, and lacks clear evidence. OpsCord transforms investigations by bringing telemetry, deployment events, and topology into a single deterministic view.

🎯 Evidence-Based Ranking A deterministic BFS traversal walks incoming dependency edges from candidate causes to the affected service. Candidates (deployments, config changes) are ranked algorithmically using time locality and corroborating telemetry.	🛡️ Robust Event Ingestion Validates incoming JSON payloads with strict provider delivery deduplication. Events are persisted to PostgreSQL with conflict detection and unified UTC timestamp normalization.
⚡ Actionable Workflows Searchable incident queues, atomic activity records (declarations, decisions, notes), and idempotent runbook application. Everything is versioned, trackable, and built for speed.	🌍 Scalable Architecture Built with Next.js App Router and PostgreSQL (via Supabase), ensuring massive scalability for enterprise-grade event ingestion and complex graph traversals.

---

🏗️ Architecture & Stack

OpsCord utilizes a highly typed, modern React stack designed for performance and reliability.

Category	Technology	Description
Framework	Next.js	App Router architecture, running on Vite via Vinext.
Language	TypeScript	End-to-end type safety from DB schema to UI.
Database	PostgreSQL	Highly reliable relational data store (Supabase recommended).
ORM	🔹 Drizzle	Lightweight and incredibly fast TypeScript ORM.
Styling	Tailwind CSS	With Radix UI & Shadcn for accessible, unstyled primitives.

Event Ingestion Flow

graph LR
    A[CI/CD / K8s / Webhooks] -->|POST JSON| B(Next.js API Route)
    B --> C{Zod Validation}
    C -->|Valid| D[Deduplication Check]
    C -.->|Invalid| E[400 Bad Request]
    D -->|New Event| F[(PostgreSQL)]
    D -.->|Duplicate| G[200 OK - Ignored]
    
    style B fill:#000,stroke:#fff,stroke-width:2px,color:#fff
    style F fill:#336791,stroke:#fff,stroke-width:2px,color:#fff

Loading

---

🚀 Quick Start

Node 22.13+ and npm are required.

1. Clone & Install

git clone https://github.com/opscord/opscord.git
cd opscord
npm run install:ci
npm run build

2. Environment Configuration

Create a .env.local file in the root directory. You will need a PostgreSQL database (like Supabase).

# .env.local
DATABASE_URL="postgresql://user:password@host:5432/dbname"

3. Database Setup

Push the Drizzle schema to your PostgreSQL database.

npm run db:generate
npx drizzle-kit push:pg

4. Start Development Server

npm run dev

Warning

Do not expose the development server to the network directly in production without an authentication layer.

---

🚢 Deployment

Deploying OpsCord is straightforward since it's a standard Next.js application.

Deploying to Vercel (Recommended)

1. Push your repository to GitHub.
2. Import the project into Vercel.
3. Set the DATABASE_URL environment variable in the Vercel dashboard.
4. Add a custom build command if needed (e.g., to run migrations during build), or just use the default Next.js settings.
5. Click Deploy.

graph TD
    A[GitHub Repo] -->|Webhook| B(Vercel Build)
    B --> C[Vercel Edge Network]
    C <--> D[(Supabase PostgreSQL)]
    
    style C fill:#000,stroke:#fff,stroke-width:2px,color:#fff
    style D fill:#336791,stroke:#fff,stroke-width:2px,color:#fff

Loading

Deploying via Docker

You can build a standalone Next.js image. (Ensure output: 'standalone' is in your next.config.ts).

# Build the image
docker build -t opscord .

# Run the container
docker run -p 3000:3000 -e DATABASE_URL="your_postgres_url" opscord

---

📡 API Reference

OpsCord is designed to integrate seamlessly with your existing CI/CD, Kubernetes, and monitoring tools.

Ingest Event POST /api/incidents/{id}/events

Ingests a new telemetry or deployment event and attaches it to an incident.

Headers: Content-Type: application/json

Payload:

{
  "externalId": "provider-event-001",
  "source": "cicd",
  "type": "deployment",
  "service": "payment-api",
  "severity": "info",
  "title": "Payment API release deployed",
  "occurredAt": "2025-05-17T05:42:00Z",
  "metadata": { "releaseId": "b7f3c2a" }
}

Responses:

• 200 OK: Event created successfully (or successfully deduplicated).
• 400 Bad Request: Invalid JSON schema.
• 409 Conflict: externalId already exists for this source but with a different payload.

List Runbooks GET /api/runbooks

Retrieves the library of available incident response runbooks.

Response:

[
  {
    "id": "rb_123",
    "title": "Database Failover Procedure",
    "version": 2,
    "steps": [ ... ]
  }
]

---

🗺️ Roadmap & Contributing

We welcome contributions! OpsCord is an evolving MVP with the following major milestones ahead:

• Ingestion: Authenticated GitHub Actions & Kubernetes adapters.
• Security: Tenant isolation, webhook rate limiting, and audit trails.
• AI: Optional evidence-grounded LLM summaries.

Read the Full Roadmap to see where we are heading.

_{Built with ❤️ for on-call engineers.}