DiunDashboard/.planning/codebase/CONVENTIONS.md

Coding Conventions

Analysis Date: 2026-03-23

Naming Patterns

Go Files:

• Package-level source files use the package name: diunwebhook.go
• Test files follow Go convention: diunwebhook_test.go
• Test-only export files: export_test.go
• Entry point: main.go inside cmd/diunwebhook/

Go Functions:

• PascalCase for exported functions: WebhookHandler, UpdateEvent, InitDB, GetUpdates
• Handler functions are named <Noun>Handler: WebhookHandler, UpdatesHandler, DismissHandler, TagsHandler, TagByIDHandler, TagAssignmentHandler
• Test functions use Test<FunctionName>_<Scenario>: TestWebhookHandler_BadRequest, TestDismissHandler_NotFound

Go Types:

• PascalCase structs: DiunEvent, UpdateEntry, Tag
• JSON tags use snake_case: json:"diun_version", json:"hub_link", json:"received_at"

Go Variables:

• Package-level unexported variables use short names: mu, db, webhookSecret
• Local variables use short idiomatic Go names: w, r, err, res, n, e

TypeScript Files:

• Components: PascalCase .tsx files: ServiceCard.tsx, AcknowledgeButton.tsx, Header.tsx, TagSection.tsx
• Hooks: camelCase with use prefix: useUpdates.ts, useTags.ts
• Types: camelCase .ts files: diun.ts
• Utilities: camelCase .ts files: utils.ts, time.ts, serviceIcons.ts
• UI primitives (shadcn): lowercase .tsx files: badge.tsx, button.tsx, card.tsx, tooltip.tsx

TypeScript Functions:

• camelCase for regular functions and hooks: fetchUpdates, useUpdates, getServiceIcon
• PascalCase for React components: ServiceCard, StatCard, AcknowledgeButton
• Helper functions within components use camelCase: getInitials, getTag, getShortName
• Event handlers prefixed with handle: handleDragEnd, handleNewGroupSubmit

TypeScript Types:

• PascalCase interfaces: DiunEvent, UpdateEntry, Tag, ServiceCardProps
• Type aliases: PascalCase: UpdatesMap
• Interface properties use snake_case matching the Go JSON tags: diun_version, hub_link

Code Style

Go Formatting:

• gofmt enforced in CI (formatting check fails the build)
• No additional Go linter (golangci-lint) configured
• go vet runs in CI
• Standard Go formatting: tabs for indentation

TypeScript Formatting:

• No ESLint or Prettier configured in the frontend
• No formatting enforcement in CI for frontend code
• Consistent 2-space indentation observed in all .tsx and .ts files
• Single quotes for strings in TypeScript
• No semicolons (observed in all frontend files)
• Trailing commas used in multi-line constructs

TypeScript Strictness:

• strict: true in tsconfig.app.json
• noUnusedLocals: true
• noUnusedParameters: true
• noFallthroughCasesInSwitch: true
• noUncheckedSideEffectImports: true

Import Organization

Go Import Order: Standard library imports come first, followed by a blank line, then the project import using the module alias:

import (
    "bytes"
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "os"
    "testing"

    diun "awesomeProject/pkg/diunwebhook"
)

• The project module is aliased as diun in both main.go and test files
• The blank-import pattern _ "modernc.org/sqlite" is used for the SQLite driver in pkg/diunwebhook/diunwebhook.go

TypeScript Import Order:

1. React and framework imports (react, @dnd-kit/core)
2. Internal imports using @/ path alias (@/hooks/useUpdates, @/components/Header)
3. Type-only imports: import type { Tag, UpdatesMap } from '@/types/diun'

Path Aliases:

• @/ maps to frontend/src/ (configured in vite.config.ts and tsconfig.app.json)

Error Handling

Go Patterns:

• Handlers use http.Error(w, message, statusCode) for all error responses
• Error messages are lowercase: "bad request", "internal error", "not found", "method not allowed"
• Internal errors are logged with log.Printf before returning HTTP 500
• Decode errors include context: log.Printf("WebhookHandler: failed to decode request: %v", err)
• Fatal errors in main.go use log.Fatalf
• errors.Is() used for sentinel error comparison (e.g., http.ErrServerClosed)
• String matching used for SQLite constraint errors: strings.Contains(err.Error(), "UNIQUE")

TypeScript Patterns:

• API errors throw with HTTP status: throw new Error(\HTTP ${res.status}`)`
• Catch blocks use console.error for logging
• Error state stored in hook state: setError(e instanceof Error ? e.message : 'Failed to fetch updates')
• Optimistic updates used for tag assignment (update UI first, then call API)

Logging

Framework: Go standard log package

Patterns:

• Startup messages: log.Printf("Listening on :%s", port)
• Warnings: log.Println("WARNING: WEBHOOK_SECRET not set ...")
• Request logging on success: log.Printf("Update received: %s (%s)", event.Image, event.Status)
• Error logging before HTTP error response: log.Printf("WebhookHandler: failed to store event: %v", err)
• Handler name prefixed to log messages: "WebhookHandler: ...", "UpdatesHandler: ..."

Frontend: console.error for API failures, no structured logging

Comments

When to Comment:

• Comments are sparse in the Go codebase
• Handler functions have short doc comments describing the routes they handle:

  // TagsHandler handles GET /api/tags and POST /api/tags
  // TagByIDHandler handles DELETE /api/tags/{id}
  // TagAssignmentHandler handles PUT /api/tag-assignments and DELETE /api/tag-assignments
  

• Inline comments used for non-obvious behavior: // Migration: add acknowledged_at to existing databases
• No JSDoc/TSDoc in the frontend codebase

Function Design

Go Handler Pattern:

• Each handler is a standalone func(http.ResponseWriter, *http.Request)
• Method checking done at the top of each handler (not via middleware)
• Multi-method handlers use switch r.Method
• URL path parameters extracted via strings.TrimPrefix
• Request bodies decoded with json.NewDecoder(r.Body).Decode(&target)
• Responses written with json.NewEncoder(w).Encode(data) or w.WriteHeader(status)
• Mutex (mu) used around write operations to SQLite

TypeScript Hook Pattern:

• Custom hooks return object with state and action functions
• useCallback wraps all action functions
• useEffect for side effects (polling, initial fetch)
• State updates use functional form: setUpdates(prev => { ... })

Module Design

Go Exports:

• Single package diunwebhook exports all types and handler functions
• No barrel files; single source file diunwebhook.go contains everything
• Test helpers exposed via export_test.go (only visible to _test packages)

TypeScript Exports:

• Named exports for all components, hooks, and utilities
• Default export only for the root App component (export default function App())
• Type exports use export interface or export type
• @/components/ui/ contains shadcn primitives (badge.tsx, button.tsx, etc.)

Git Commit Message Conventions

Format: Conventional Commits with bold markdown formatting

Pattern: **<type>(<scope>):** <description>

Types observed:

• feat - new features
• fix - bug fixes
• docs - documentation changes
• chore - maintenance tasks (deps, config)
• refactor - code restructuring
• style - UI/styling changes
• test - test additions

Scopes observed: docs, compose, webhook, ci, ui, main, errors, sql, api, deps, stats

Examples:

**feat(webhook):** add `WEBHOOK_SECRET` for token authentication support
**fix(ci):** improve version bump script for robustness and compatibility
**docs:** expand `index.md` with architecture, quick start, and tech stack
**chore(docs):** add `.gitignore` for `docs` and introduce `bun.lock` file

Multi-change commits: Use bullet list with each item prefixed by - **type(scope):**

---

Convention analysis: 2026-03-23