Developer Guide
The Developer Guide provides architecture documentation, development workflows, and contribution guidelines for the pgEdge AI DBA Workbench project.
Project Overview
The pgEdge AI DBA Workbench consists of four components that work together to monitor and manage PostgreSQL database estates.
- The collector is a Go service that gathers metrics from monitored PostgreSQL instances and stores the data in a central datastore.
- The alerter is a Go service that evaluates alert rules against collected metrics and sends notifications through configured channels.
- The server is a Go service that implements the Model Context Protocol (MCP) and provides REST APIs for the web client.
- The client is a React/TypeScript web application that displays dashboards, alerts, and AI-generated insights.
Development Prerequisites
Install the following tools before starting development:
- Go 1.24 or later for building server-side components.
- Node.js 18 or later for building the web client.
- PostgreSQL 14 or later for running database tests.
- Git for version control.
- Make for build automation.
Install the Go linter with the following command:
go install \
github.com/golangci/golangci-lint/cmd/golangci-lint@latest
Getting Started
Clone the repository from GitHub:
git clone \
https://github.com/pgEdge/ai-dba-workbench.git
cd ai-dba-workbench
Build all components from the top-level directory:
make all
Run the full test suite to verify the setup:
make test-all
Project Structure
The repository follows this directory layout:
ai-dba-workbench/
alerter/ Alert monitoring service
src/ Source code
client/ Web client (React/TypeScript)
src/ Source code
collector/ Data collector service
src/ Source code
server/ MCP server
src/ Source code
pkg/ Shared Go packages
docs/ Unified documentation
examples/ Example configurations
Each Go component has its own go.mod under the src/
subdirectory. Build commands must run from within the
src/ directory of each component.
Component Documentation
Collector
- Testing Guide covers the collector architecture, workflows, and test strategy.
- Adding Probes explains how to create new metric probes.
Alerter
- Testing Guide covers the alerter architecture, workflows, and test strategy.
- Adding Rules explains how to create new alert rules.
Server
- Server Architecture describes the MCP server internals, transport layer, and extension points.
Client
- Client Architecture describes the React component structure, state management, and build workflow.
Design Documents
- Node Role Probe Design documents the design for detecting PostgreSQL node roles within cluster topologies.
Contributing
See the Contributing Guide for instructions on submitting code, running quality checks, and following the project coding standards.