Development Guide

Run the platform locally with hot reload for frontend and backend development

This guide covers running the platform in development mode, building for production, and the available Makefile targets.

Development mode

Run the backend and frontend in separate terminals for hot reload on both:

1. Start the backend

   cd dorgu-platform
   make run
   

   The Go server starts on port 8080 and connects to your current Kubernetes context.

2. Start the frontend

   cd dorgu-platform/web
   npm install
   npm run dev
   

   Vite starts on port 5173 with hot module reloading. API calls (/api/*) and WebSocket (/ws) are proxied to the backend on port 8080.

3. Open in browser

   Open http://localhost:5173 for the development server with hot reload.

In development mode, use port 5173 (Vite) for the frontend. Port 8080 (Go) serves the API but won’t have the latest frontend changes unless you rebuild.

Makefile targets

Target	Description
make frontend	Build the React app (web/dist)
make build	Build Go binary with embedded frontend
make run	Run the Go backend in development mode
make test	Run Go tests with coverage
make lint	Run linters
make clean	Remove build artifacts

Production build

Build a single binary with the frontend embedded:

make build

This runs three steps:

1. Builds the React app to web/dist
2. Copies web/dist to pkg/server/static
3. Compiles the Go binary with //go:embed static

The resulting binary at ./bin/server contains everything — no external files needed.

Project dependencies

Backend

Dependency	Version	Purpose
k8s.io/client-go	v0.29.0	Kubernetes client
k8s.io/apimachinery	v0.29.0	Kubernetes API types
github.com/gorilla/mux	v1.8.1	HTTP router
github.com/gorilla/websocket	v1.5.3	WebSocket protocol

Frontend

Dependency	Version	Purpose
react	v19.2	UI framework
react-router-dom	v7.13	Client-side routing
@tanstack/react-query	v5.91	Server state management
axios	v1.13	HTTP client
tailwindcss	v3.4	Utility-first CSS
lucide-react	v0.577	Icons
vite	v8.0	Build tool

Adding a new API endpoint

1. Add the handler function in pkg/api/clusters.go (or create a new file)
2. Register the route in pkg/server/server.go in setupRoutes()
3. Add tests in pkg/api/*_test.go
4. Run make test

Adding a new frontend component

1. Create the component in web/src/components/
2. Create a React Query hook in web/src/hooks/ if data fetching is needed
3. Add the TypeScript interface in web/src/lib/api.ts
4. Import and use in the relevant page
5. Test in dev mode: npm run dev

Testing

# Run Go tests
make test

# Run with race detector
go test -v -race ./...

# Run frontend type checking
cd web && npx tsc --noEmit

Architecture

How the platform is structured

Installation

Production deployment options