# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Grafana-Zabbix is a hybrid Grafana plugin connecting Grafana to Zabbix monitoring infrastructure. It consists of three components:
- **Zabbix App** (`/src`) - Container app plugin
- **Zabbix Data Source** (`/src/datasource`) - TypeScript frontend + Go backend for querying Zabbix
- **Problems Panel** (`/src/panel-triggers`) - React panel for displaying Zabbix problems/triggers

## Build Commands

```bash
# Install all dependencies
make install           # or: yarn install && go install -v ./pkg/

# Development
yarn dev               # Watch mode for frontend
make run-backend       # Watch mode for backend (uses bra)

# Production build
make build             # or: yarn build && mage -v build:backend

# Distribution (all platforms)
make dist

# After building, restart Grafana to reload the plugin
podman container stop grafana && podman container start grafana
```

## Testing

```bash
# Frontend tests (Jest)
yarn test              # Watch mode
yarn test:ci           # CI mode, all tests

# Run specific test file
yarn test datasource.test.ts
yarn test Problems.test.tsx

# Backend tests (Go)
go test ./pkg/...
```

Test files are located alongside source code with `.test.ts` or `.test.tsx` extensions:
- `src/datasource/specs/*.test.ts`
- `src/datasource/components/**/*.test.tsx`
- `src/datasource/zabbix/**/*.test.ts`
- `src/panel-triggers/components/**/*.test.tsx`

## Linting and Type Checking

```bash
yarn lint              # Check for linting errors
yarn lint:fix          # Auto-fix lint and formatting issues
yarn typecheck         # TypeScript type checking
```

## Development Environment

```bash
yarn server            # Start Grafana + Zabbix via Docker Compose
yarn server:down       # Stop and remove containers
```

Docker setup in `/devenv/` includes multiple Zabbix versions (5.0, 6.0, 7.0, 7.2, 7.4) for compatibility testing.

## Architecture

**Frontend-Backend Communication**: Frontend queries go through Grafana's backend proxy to the plugin backend executable (`gpx_zabbix-datasource`), which handles Zabbix API calls. Uses gRPC via Grafana Plugin SDK.

**Key Frontend Packages**:
- `/src/datasource/datasource.ts` - Main ZabbixDatasource class
- `/src/datasource/zabbix/` - Zabbix API client logic
- `/src/datasource/components/` - Query editor, config editor components
- `/src/panel-triggers/components/` - Problems panel components

**Key Backend Packages** (`/pkg/`):
- `datasource/` - Main backend logic
- `zabbix/` - Zabbix API interactions
- `zabbixapi/` - Low-level API connector
- `cache/` - Caching layer

## Requirements

- Node.js: v24 (see `.nvmrc`)
- Yarn: v4.12.0
- Go: 1.25
- Grafana: >=11.6.0

## PR Workflow

Run `yarn changeset` to create a changeset file for your PR. This is required for version bumping and changelog generation.

## Debugging Backend

```bash
make build-debug       # Build with debug flags
./debug-backend.sh     # Attach delve debugger (after starting Grafana)
```

VS Code debug config connects to delve on port 3222.