# Contributing

Thank you for your interest in contributing to DIUN Webhook Dashboard!

## Prerequisites

- [Go 1.26+](https://go.dev/dl/)
- [Bun](https://bun.sh/) (frontend package manager and runtime)

## Project Structure

```
cmd/diunwebhook/       — main application entrypoint
pkg/diunwebhook/       — core library (handlers, DB, models)
frontend/              — React SPA (Bun + Vite + React 19 + Tailwind + shadcn/ui)
docs/                  — VitePress documentation site
.gitea/workflows/      — CI/CD workflows (Gitea Actions)
Dockerfile             — 3-stage multi-stage build
compose.yml            — deploy compose (pulls from Gitea registry)
compose.dev.yml        — dev compose (builds locally)
```

## Development Setup

### Backend

Start the Go server (serves on `:8080` by default):

```bash
go run ./cmd/diunwebhook/
```

### Frontend (hot reload)

The frontend dev server runs on `:5173` and proxies `/api` and `/webhook` requests to the Go backend on `:8080`:

```bash
cd frontend
bun install
bun run dev    # http://localhost:5173
```

Make sure the Go backend is running alongside the frontend dev server.

### Docker Compose (dev)

Builds the image locally from source:

```bash
docker compose -f compose.dev.yml up -d
# open http://localhost:8080
```

## Building from Source

```bash
# 1. Build the frontend
cd frontend && bun install && bun run build && cd ..

# 2. Build the Go binary
go build -o app ./cmd/diunwebhook/

# 3. Run it (frontend/dist/ must be in the working directory)
./app
```

## Testing

Run all tests with coverage:

```bash
go test -v -coverprofile=coverage.out -coverpkg=./... ./...
```

Run a single test:

```bash
go test -v -run TestWebhookHandler ./pkg/diunwebhook/
```

Aim for 80-90% coverage. Coverage below 80% will emit a warning in CI but will not fail the pipeline.

## CI/CD

### CI Pipeline

**Workflow:** `.gitea/workflows/ci.yml`
**Trigger:** push or PR to `develop`

Steps:
1. Check formatting (`gofmt`)
2. Run `go vet`
3. Run tests with coverage
4. Build the binary

### Release Pipeline

**Workflow:** `.gitea/workflows/release.yml`
**Trigger:** manual dispatch

Steps:
1. Run tests
2. Bump version and tag
3. Build and push Docker image to Gitea registry
4. Create a Gitea release with changelog

## Documentation

The documentation site is built with [VitePress](https://vitepress.dev/) and lives in `docs/`.

```bash
cd docs
bun install        # install deps
bun run dev        # dev server on :5174
bun run build      # production build
bun run preview    # preview the build
```