whodb

The Problem

Developers need a single tool that can explore many data stores (Postgres, MySQL, SQLite, MongoDB, Redis, MariaDB, Elastic Search, ClickHouse) and let them issue natural‑language queries. Existing GUIs are heavyweight, start slowly, and lack a programmable API, forcing teams to juggle separate CLIs, IDE plugins, and ad‑hoc scripts.

What This Does

WhoDB bundles a Go‑based backend (core/) that exposes a GraphQL API and a React frontend (frontend/) that renders a spreadsheet‑style UI plus a chat window for AI‑driven SQL generation. The CLI (cli/) wraps the same backend for headless use and ships pre‑built binaries for all major OS/archs (see the cli/npm-package/packages/ directories).

Key modules:

Module	Role
`core/graph/generated.go`	Generates the executable GraphQL schema; invoked by the server entry point.
`core/src/log/log.go`	Centralised logger used by > 65 callers.
`cli/internal/database/manager.go`	Loads saved connection definitions, reads/writes config files, and contacts remote model services for AI suggestions.
`core/graph/schema.resolvers.go`	Implements GraphQL resolvers (login, CRUD on storage units, AI‑assisted queries).
`cli/pkg/output/output.go`	Formats CLI output (JSON, table, quiet mode).
`cli/pkg/mcp/server.go`	Starts the local GraphQL server for the CLI.
`cli/internal/tui/browser_view.go`	Renders the interactive terminal UI for data browsing.
`cli/internal/config/config.go`	Determines the default config directory, reads the user’s `whodb.yaml`.

How It Is Wired

Startup – Execution begins at cli/main.go:34 (func main). It creates the CLI root command, registers sub‑commands (connect, query, etc.), and ultimately calls RunApp in desktop-common/run.go:41 when the desktop build is used.

Server Launch – The CLI’s RunApp invokes cli/pkg/mcp/server.NewServer, which builds the GraphQL schema via core/graph/generated.go and registers resolvers from core/graph/schema.resolvers.go.

Configuration Load – Early in the flow, cli/internal/config/config.go:GetConfigPath is called (≈ 20 callers) to locate whodb.yaml. cli/internal/database/manager.go:LoadConfig parses it, populating the in‑memory metadata cache.

Database Interaction – Resolver functions such as AddStorageUnit, GetRows, UpdateStorageUnit (each called 20‑50 times across the code base) ultimately call cli/internal/database/manager.go helpers (WithError, WithField) which perform the actual driver calls (Postgres, MySQL, etc.).

AI/Network Calls – Several resolver paths (Login, UpdateSettings, AddStorageUnit) invoke external model services (e.g., OpenAI) – see core/graph/schema.resolvers.go where a network request is made after a logger call.

Output – CLI commands pipe results through cli/pkg/output/output.go to honour --json, --quiet, or default table formatting.

Filesystem Side‑effects – The only outbound file writes are configuration persistence (SaveWindowState → os.WriteFile) and occasional export of CSV data (ExportData → FormatCSVHeader).

Hotspots – The import‑cycle‑prone files frontend/src/config/routes.tsx, frontend/src/components/loading.tsx, frontend/src/components/page.tsx form a circular dependency, increasing change‑impact risk. The heroicons module (frontend/src/components/heroicons) is a hub with 31 downstream imports, so any API change there ripples widely.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/whodb
cd whodb

# Install frontend deps (pnpm lock present)
pnpm install        # pulls React, GraphQL, etc.

# Build the CLI container (Dockerfile in cli/)
docker build -f cli/Dockerfile -t whodb-cli .

# Or build the native binary (Makefile in cli/)
make -C cli          # produces ./cli/whodb (Linux x64)

# Run the desktop app (if you have a macOS/Windows build)
# Binary is in the respective platform package under cli/npm-package/
./cli/npm-package/packages/whodb-cli-darwin-x64/whodb   # example

# Start the server (CLI mode)
./cli/whodb serve --config ./whodb.yaml

Configuration lives in the user config directory returned by cli/internal/config/config.go:GetConfigDir (e.g., ~/.config/whodb/whodb.yaml). Connections are defined there; the CLI reads them on start and populates the UI.

Real‑World Use

A micro‑service team adds a new ClickHouse cluster. They drop a connection block into ~/.config/whodb/whodb.yaml, then run whodb serve. The GraphQL endpoint instantly reflects the new schema, allowing developers to explore tables via the React UI or issue “show me the top 10 rows where latency > 100 ms” in the chat window. The same query can be scripted via whodb query --sql "SELECT …" in CI pipelines.

Code Health & Issues

High – CI never runs tests – .github/workflows/* contain no test step despite 65 test files.
High – continue-on-error masks failures – .github/workflows/_build-docker.yml line 125.
Medium – Base images not pinned – cli/Dockerfile uses mutable tags (golang:1.25-alpine3.22).
Medium – No dependency‑vulnerability gate – No scan step in any workflow.
Medium – Checkout persists token – persist-credentials not disabled in Docker build workflow.
Medium – Container runs as root – No USER directive in cli/Dockerfile.
Low – No job timeout – _build-docker-cli.yml lacks timeout-minutes.

All findings are deterministic outputs from the static analysis; each includes a concrete fix path.

The Bottom Line

WhoDB delivers a cohesive Go + React stack that unifies multi‑database exploration and AI‑assisted querying, with a CLI and desktop builds that share a single GraphQL core. The codebase is functional but suffers from CI mis‑configuration, container hardening gaps, and a few front‑end import cycles that could impede rapid change. It is a solid foundation for teams needing a lightweight, extensible data explorer, provided they address the highlighted health issues before production deployment.