The Problem

Superlog is an open-source agentic telemetry system that ingests OpenTelemetry data (traces, logs, metrics), groups noisy signals into incidents, and provides a local-first product surface for debugging production systems. The repository contains four self-contained projects — a web app, API, OTLP proxy, and worker processes — but lacks the automated gates and configuration expected of production software. Engineers inheriting this code will face undetected regressions, security misconfigurations, and a codebase where changes to high-impact modules ripple widely without validation.

What This Does

This repository implements a full-stack observability platform. The apps/api (HTTP API, 374 files) handles request routing, GitHub and Linear webhook processing, incident management, and ClickHouse-backed telemetry queries. apps/web (Vite/React frontend) provides the user interface for incident exploration and settings. apps/worker runs background processes for incident grouping, agent orchestration, and telemetry ingestion. apps/proxy serves as the OTLP intake endpoint. Core logic lives in packages/db (Drizzle schema and migrations) and packages/fingerprint (telemetry fingerprinting helpers). Four entry points anchor execution: handler in apps/web/src/App.tsx:217, main in apps/api/scripts/test-agent-tracking-e2e.ts:265, loadIncidentsBucketStats in apps/api/src/index.ts:1832, and loadSpanNamesForIssueSamples in apps/api/src/index.ts:2558. The internal call graph resolves 2,539 function-to-function edges; useFetcher is called from 108 places, findFirst from 80, and where from 77, establishing these as the most breakable points in a change.

How It Is Wired

Execution begins at handler in apps/web/src/App.tsx:217, which is itself called from one place. From there, user interactions flow through useFetcher (108 call sites) and findFirst (80 call sites) into the API layer at apps/api/src/index.ts, where loadIncidentsBucketStats reaches 32 downstream functions and loadSpanNamesForIssueSamples reaches 25. The most connected hub is apps/web/src/api.ts, which defines useFetcher, useMe, and useSystemCapabilities and is imported by 36 other modules — a change there ripples widely. apps/api/src/index.ts also defines the API entry point with 98 functions and 76 types; it is called from 27 other files and directly handles database queries, including query calls that build SQL with interpolated strings rather than bound parameters. apps/worker/src/agent-run-context (14 importers, 3 exported) and apps/worker/src/logger (29 importers, 0 exported) form the worker orchestration layer. The database schema in packages/db/src/schema.ts defines 85 types and is imported by 4 modules; it is the single source of truth for agent runs, incidents, and schema migrations. apps/api/src/github.ts (51 functions, 20 types) reads and writes a database and performs cryptographic operations for GitHub webhook signature verification. apps/web/src/Settings.tsx performs a cryptographic or secret-generating operation, likely for sidebar navigation hashing.

Traced paths from entry point to process exit: main -> seed routes through model inference and db.insert(schema.agentRuns).values({ incidentId: i }); loadIncidentsBucketStats -> fetchIncidentTimeseriesPairs -> query -> result reads via tx.query.orgMembers.findFirst. These are shortest paths over resolved edges; framework callbacks are invisible in the call graph.

How To Use It

Setup: pnpm install installs dependencies across all workspaces. The project uses pnpm 9+ as package manager (verified by package.json files). Docker is required for local services.

Configuration: Environment variables are defined in apps/api/.env.example and apps/proxy/.env.example. Required vars likely include database connection strings, API keys for GitHub/Linear, and ClickHouse credentials. No .env file is committed; the example files show the expected shape.

Running it: Start the local stack with docker compose up -d, then run pnpm --filter @superlog/db db:migrate to apply Postgres migrations, and pnpm dev to start development mode. The default services listen at http://localhost:5173 (web), http://localhost:4100 (API), and http://localhost:4101 (OTLP intake).

Typechecking: pnpm typecheck runs the type checker across the codebase.

Code Health & Issues

The static analysis identified 55 findings across 15 high, 40 medium, and 0 low severity categories. Key issues:

  • [HIGH/cognitive_load] Oversized files: apps/web/src/api.ts, packages/db/src/schema.ts, apps/api/src/mcp/clickhouse.ts (1,769 lines each; hard to hold in one head; changes ripple widely). Fix: split into cohesive units by responsibility.
  • [HIGH/clarity] Hub module: apps/web/src/api.ts is depended on by 36 modules; churn here is high-blast-radius. Fix: keep stable and small; move volatile logic out.
  • [HIGH/cognitive_load] Deep nesting: apps/web/src/Explore.tsx, apps/web/src/Settings.tsx, apps/web/src/dashboards/WidgetForm.tsx — max indentation depth 6. Fix: flatten with early returns/guard clauses.
  • [MEDIUM/resilience] Empty catch block in apps/web/src/design/ui.tsx silently discards errors. Fix: handle, rethrow, or at least log.
  • [HIGH/clarity] Duplicated code blocks: 793 repeated 6-line blocks across 131 files, including apps/api/src/github.test.ts and apps/api/src/index.ts. Fix: extract shared helpers.
  • [MEDIUM/SDLC] No CI/CD pipeline — no automated build/test gate. .github/ or CI config is absent. Every change merges with nobody having run the build.
  • [HIGH/Security] Wildcard CORS origin * with credentials enabled in apps/api/src/index.ts. Any page on the internet can call the API with the browser's cookies attached. Fix: replace with explicit allow list.
  • [HIGH/SQL injection risk] .query() with interpolated query string in apps/api/src/index.ts. A value spliced into SQL is read as syntax. Fix: pass placeholders and hand values to the driver as parameters.
  • [MEDIUM/Supply chain] No Dependabot or Renovate configured. 9 manifest files go unpatched until manual audit.
  • [MEDIUM/Container] apps/api/Dockerfile uses node:20-slim without digest pinning or non-root USER directive.
  • [LOW/Hygiene] Missing .editorconfig, .gitattributes, and formatter configuration.

The Bottom Line

This is a functional, well-structured observability platform with clear project separation across four apps and two packages. The codebase is TypeScript-heavy with solid module boundaries and a resolved call graph that makes impact analysis tractable. However, it ships without CI/CD, with critical security misconfigurations (wildcard CORS + credentials, SQL interpolation), and with oversized, duplicated files that raise the cost of any change. Teams needing a self-hosted telemetry incident system can use this today, but should budget engineering time to add a CI pipeline, fix the CORS and SQL injection issues, and refactor the largest oversized files before promoting to production.