Jean-Luc Makiola
db9f47649d
All checks were successful
CI / build-test (push) Successful in 1m3s
- Reflect addition of React SPA, SQLite persistence, and tag management - Update quick start guide for backend and frontend setup - Document full API routes and database schema - Revise project structure for recent refactor - Improve production and testing notes for clarity
63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Run all tests with coverage
|
|
go test -v -coverprofile=coverage.out -coverpkg=./... ./...
|
|
|
|
# Run a single test
|
|
go test -v -run TestWebhookHandler ./pkg/diunwebhook/
|
|
|
|
# Run the app locally
|
|
go run ./cmd/diunwebhook/
|
|
|
|
# Build Docker image
|
|
docker build -t diun-webhook-dashboard .
|
|
|
|
# Run with Docker Compose
|
|
docker compose up -d
|
|
|
|
# Frontend (from frontend/ directory)
|
|
bun install # install deps
|
|
bun run dev # dev server on :5173 (proxies /api and /webhook to :8080)
|
|
bun run build # production build → frontend/dist/
|
|
```
|
|
|
|
CI warns (but does not fail) when coverage drops below 80%.
|
|
|
|
## Architecture
|
|
|
|
The app is a Go HTTP server that receives [DIUN](https://crazymax.dev/diun/) webhook events and exposes them via a JSON API and a React SPA dashboard. Events are persisted to a SQLite database (`diun.db`) using `modernc.org/sqlite` (pure Go, no CGO).
|
|
|
|
**Package layout:**
|
|
- `pkg/diunwebhook/` — core library: `DiunEvent`, `UpdateEntry`, and `Tag` structs; SQLite-backed storage (guarded by `sync.Mutex`); HTTP handlers (`WebhookHandler`, `UpdatesHandler`, `DismissHandler`, `TagsHandler`, `TagByIDHandler`, `TagAssignmentHandler`)
|
|
- `cmd/diunwebhook/main.go` — calls `InitDB()`, wires handlers onto `net/http`'s default mux, serves `./frontend/dist` at `/`, listens on `:8080` (overridable via `PORT` env var), graceful shutdown
|
|
- `pkg/diunwebhook/diunwebhook_test.go` — external test package (`package diunwebhook_test`); uses `httptest` for handler tests
|
|
- `pkg/diunwebhook/export_test.go` — test-only exports
|
|
- `frontend/` — React SPA (Bun + Vite + React 19 + Tailwind CSS + shadcn/ui + dnd-kit)
|
|
|
|
**Database schema (SQLite):**
|
|
- `updates` — one row per image (PRIMARY KEY `image`), stores full event fields plus `received_at` and `acknowledged_at`
|
|
- `tags` — user-defined tag/group names (`id` INTEGER PK, `name` UNIQUE)
|
|
- `tag_assignments` — maps `image` → `tag_id` (FK with CASCADE delete)
|
|
|
|
**API routes:**
|
|
- `POST /webhook` — accept a DIUN event
|
|
- `GET /api/updates` — return all events (with tag and acknowledged state)
|
|
- `PATCH /api/updates/{image}` — mark an event as acknowledged (dismiss)
|
|
- `GET /api/tags` — list all tags
|
|
- `POST /api/tags` — create a tag
|
|
- `DELETE /api/tags/{id}` — delete a tag (cascades to assignments)
|
|
- `PUT /api/tag-assignments` — assign an image to a tag
|
|
- `DELETE /api/tag-assignments` — unassign an image from its tag
|
|
|
|
**Key data flow:**
|
|
1. DIUN POSTs JSON to `/webhook` → `WebhookHandler` decodes into `DiunEvent` → upserted into `updates` table (latest event per image wins, resets acknowledged state)
|
|
2. React SPA polls `GET /api/updates` every 5 s → `UpdatesHandler` returns map of `UpdateEntry` (includes event, received time, acknowledged flag, and optional tag)
|
|
3. User can dismiss updates via `PATCH /api/updates/{image}` and organize images into tag groups via the tag/assignment endpoints
|
|
|
|
**Test helpers exposed from the library package** (not part of the public API, only for tests): `GetUpdatesMap()`, `UpdatesReset()`, `UpdateEvent()`, `ResetTags()`.
|