HyperDX Development Guide

What is HyperDX?

HyperDX is an observability platform that helps engineers search, visualize, and monitor logs, metrics, traces, and session replays. It's built on ClickHouse for blazing-fast queries and supports OpenTelemetry natively.

Core value: Unified observability with ClickHouse performance, schema-agnostic design, and correlation across all telemetry types in one place.

Architecture (WHAT)

This is a monorepo with three main packages:

packages/app - Next.js frontend (TypeScript, Mantine UI, TanStack Query)
packages/api - Express backend (Node.js 22+, MongoDB for metadata, ClickHouse for telemetry)
packages/common-utils - Shared TypeScript utilities for query parsing and validation

Data flow: Apps → OpenTelemetry Collector → ClickHouse (telemetry data) / MongoDB (configuration/metadata)

Development Setup (HOW)

yarn setup          # Install dependencies
yarn dev            # Start full stack (Docker + local services)

The project uses Yarn 4.5.1 workspaces. Docker Compose manages ClickHouse, MongoDB, and the OTel Collector.

Working on the Codebase (HOW)

Before starting a task, read relevant documentation from the agent_docs/ directory:

agent_docs/architecture.md - Detailed architecture patterns and data models
agent_docs/tech_stack.md - Technology stack details and component patterns
agent_docs/development.md - Development workflows, testing, and common tasks
agent_docs/code_style.md - Code patterns and best practices (read only when actively coding)

Tools handle formatting and linting automatically via pre-commit hooks. Focus on implementation; don't manually format code.

Key Principles

Multi-tenancy: All data is scoped to Team - ensure proper filtering
Type safety: Use TypeScript strictly; Zod schemas for validation
Existing patterns: Follow established patterns in the codebase - explore similar files before implementing
Component size: Keep files under 300 lines; break down large components
UI Components: Use custom Button/ActionIcon variants (primary, secondary, danger) - see agent_docs/code_style.md for required patterns
Testing: Tests live in __tests__/ directories; use Jest for unit/integration tests

Running Tests

Each package has different test commands available:

packages/app (unit tests only):

cd packages/app
yarn ci:unit           # Run unit tests
yarn dev:unit          # Watch mode for unit tests
yarn test:e2e          # Run end-to-end tests
yarn test:e2e:ci       # Run end-to-end tests in CI

packages/api (integration tests only):

docker compose -f ./docker-compose.ci.yml up -d # Start the integration test docker services
cd packages/api
yarn ci:int            # Run integration tests
yarn dev:int           # Watch mode for integration tests
cd ../.. && docker compose -f ./docker-compose.ci.yml down # Stop the integration test docker services

packages/common-utils (both unit and integration tests):

cd packages/common-utils
yarn ci:unit           # Run unit tests
yarn dev:unit          # Watch mode for unit tests
yarn ci:int            # Run integration tests
yarn dev:int           # Watch mode for integration tests

To run a specific test file or pattern:

yarn ci:unit <path/to/test.ts>                           # Run specific test file
yarn ci:unit --testNamePattern="test name pattern"       # Run tests matching pattern

Important Context

Authentication: Passport.js with team-based access control
State management: Jotai (client), TanStack Query (server), URL params (filters)
UI library: Mantine components are the standard (not custom UI)
Database patterns: MongoDB for metadata with Mongoose, ClickHouse for telemetry queries

GitHub Action Workflow (when invoked via @claude)

When working on issues or PRs through the GitHub Action:

Before writing any code, post a comment outlining your implementation plan — which files you'll change, what approach you'll take, and any trade-offs or risks. Use gh issue comment for issues or gh pr comment for PRs.
After making any code changes, always run these in order and fix any failures before opening a PR:
- make ci-lint — lint + TypeScript type check
- make ci-unit — unit tests
Write a clear PR description explaining what changed and why.

Need more details? Check the agent_docs/ directory or ask which documentation to read.

4.5 KiB Raw Blame History