Zabbix AI Troubleshooting System

Overview

An AI-powered web application that automatically analyzes Zabbix monitoring installations to identify configuration issues, setup problems, and best practice violations. The system connects to Zabbix servers via their JSON-RPC API, retrieves system data, and uses OpenAI's GPT-4 to provide intelligent diagnostics with step-by-step fix suggestions.

Core Purpose: Simplify Zabbix troubleshooting by automating the detection of common configuration errors, installation problems, and performance concerns through AI-driven analysis.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Framework: React 18 with TypeScript using Vite as the build tool

UI Framework: shadcn/ui component library built on Radix UI primitives with Tailwind CSS for styling

Design System:

• Dark-first design optimized for IT monitoring workflows
• Custom color palette with semantic meanings (critical/error, warning, success, info, analyzing)
• Typography using Inter for UI and JetBrains Mono for code/logs
• Follows "New York" style variant from shadcn/ui

State Management:

• TanStack Query (React Query) for server state and API interaction
• React hooks for local component state
• Custom query client with automatic error handling and 401 response management

Routing: Wouter for lightweight client-side routing

Key Design Patterns:

• Component composition with Radix UI primitives
• Form handling via react-hook-form with Zod validation
• Toast notifications for user feedback
• Theme provider supporting light/dark modes with localStorage persistence

Backend Architecture

Runtime: Node.js with Express server

Language: TypeScript with ES modules

API Design: RESTful endpoints under /api namespace

• /api/zabbix/test - Test Zabbix connection and retrieve system info
• /api/zabbix/info - Get current Zabbix system information
• /api/analysis/latest - Retrieve most recent analysis results
• /api/analysis/start - Trigger new AI-powered analysis
• /mock-zabbix/api_jsonrpc.php - Mock Zabbix server for testing (no real Zabbix required)

Data Flow:

1. Client submits Zabbix credentials via connection form
2. Server validates connection through Zabbix JSON-RPC API
3. System retrieves hosts, items, triggers, templates, and problems
4. AI analyzer processes data through OpenAI GPT-4
5. Structured issues returned with severity, categories, and fix suggestions

Storage Strategy:

• In-memory storage implementation (MemStorage class)
• Interface-based design (IStorage) allowing future database integration
• Stores connection credentials and analysis results
• No persistence across server restarts

Key Services:

• ZabbixClient: Handles all Zabbix API communication via JSON-RPC 2.0
• AIAnalyzer: Orchestrates OpenAI API calls for configuration analysis
• Storage: Manages temporary data persistence

Data Schema & Validation

Schema Definition: Centralized in shared/schema.ts using Zod for runtime validation

Core Data Types:

• ZabbixConnection: API URL, username, password
• Issue: Severity-categorized problems with AI analysis and suggested fixes
• AnalysisResult: Complete analysis report with timestamp, status, and issues array
• ZabbixSystemInfo: Version, connection status, and resource counts

Validation Strategy: Zod schemas provide both TypeScript types and runtime validation, shared between client and server

AI Integration

Provider: OpenAI GPT-4 (configured via environment variables)

Prompt Engineering:

• System prompt establishes expert Zabbix administrator persona
• Structured to identify: configuration problems, installation issues, best practice violations, performance concerns, template errors
• Enforces JSON response format for consistent parsing

Response Structure: Issues include severity levels, categories, descriptions, affected items, AI analysis explanations, and confidence-scored fix suggestions

Error Handling: Try-catch blocks with fallback error responses when AI analysis fails

External Dependencies

Third-Party Services

OpenAI API:

• Model: GPT-4 (gpt-4o)
• Configuration via environment variables: AI_INTEGRATIONS_OPENAI_API_KEY, AI_INTEGRATIONS_OPENAI_BASE_URL
• Used for intelligent Zabbix configuration analysis

Zabbix JSON-RPC API:

• Version-agnostic integration (tested with Zabbix 6.x+)
• Authentication via user credentials
• Retrieves: API version, hosts, items, triggers, templates, problems

Mock Zabbix Server (for testing without real Zabbix):

• Built-in endpoint: http://localhost:5000/mock-zabbix/api_jsonrpc.php
• Accepts any username/password credentials
• Returns realistic test data including:
  • 3 hosts (web-server-01, db-server-01, app-server-01)
  • 3 monitoring items (CPU utilization, Memory utilization, MySQL service check)
  • 3 triggers (High CPU usage, MySQL down [FIRING], Disk space low)
  • 1 active problem (MySQL is down on Database Server 01)
  • 2 templates (Template OS Linux, Template DB MySQL)
• Perfect for testing and demo purposes without Zabbix installation

Database

Current: In-memory storage (no database)

Planned: PostgreSQL via Drizzle ORM

• Configuration present in drizzle.config.ts
• Schema defined in shared/schema.ts (currently for validation only)
• NeonDB serverless driver installed (@neondatabase/serverless)
• Migration setup configured but not active

Key NPM Packages

Frontend:

• react & react-dom - UI framework
• @tanstack/react-query - Server state management
• react-hook-form - Form handling
• zod - Schema validation
• wouter - Routing
• @radix-ui/* - Headless UI primitives (20+ components)
• tailwindcss - Utility-first CSS
• class-variance-authority & clsx - Dynamic className generation

Backend:

• express - Web server
• openai - OpenAI API client
• drizzle-orm - SQL ORM (prepared for future use)
• tsx - TypeScript execution for development

Build Tools:

• vite - Frontend build tool and dev server
• esbuild - Backend bundling for production
• typescript - Type checking

Development Environment

Replit Integration:

• Custom Vite plugins for dev banner and cartographer (development only)
• Runtime error overlay modal for debugging
• Environment detection via REPL_ID and NODE_ENV

Font Loading: Google Fonts CDN for Inter and JetBrains Mono typefaces

Session Management: connect-pg-simple installed for future PostgreSQL session storage