> ## Documentation Index
> Fetch the complete documentation index at: https://dorguai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="Start the backend">
    ```bash theme={null}
    cd dorgu-platform
    make run
    ```

    The Go server starts on port 8080 and connects to your current Kubernetes context.
  </Step>

  <Step title="Start the frontend">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Open in browser">
    Open [http://localhost:5173](http://localhost:5173) for the development server with hot reload.
  </Step>
</Steps>

<Info>
  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.
</Info>

## 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:

```bash theme={null}
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

```bash theme={null}
# Run Go tests
make test

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

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

<CardGroup cols={2}>
  <Card title="Architecture" icon="sitemap" href="/platform/architecture/overview">
    How the platform is structured
  </Card>

  <Card title="Installation" icon="download" href="/platform/installation">
    Production deployment options
  </Card>
</CardGroup>