Skip to content
Pulci Nella — the Clownware markPulci Nella — the Clownware markClownware Docs

ADR-012: Routing, Handler, and UI Patterns

Date: 2025-05-01

Status

Section titled “Status”

Accepted (template engine amended by ADR-017)

Context

Section titled “Context”

Consistent routing, handler structure, and UI update patterns are important for maintainability and developer experience. The team must formalize conventions for Go HTTP routing, handler organization, and dynamic UI updates (HTMX/Alpine.js).

Decision

Section titled “Decision”
  • Use chi router with route groups for feature/module organization.
  • Follow RESTful conventions for endpoint naming.
  • Keep handler functions focused and short; business logic is separated from HTTP layer.
  • Use HTMX for partial UI updates, with Go templates rendering HTML fragments.
  • Alpine.js is used only for client-side interactivity that cannot be handled server-side.
  • Error feedback to users is delivered via HTMX triggers and reusable error partials.

Amended 2026-08-02: ADR-017 superseded ADR-008’s html/template — HTMX fragments are rendered by templ partials in internal/view/partials/ (raw html/template is forbidden; Constitution rule 2, adr017-no-html-template). The HTMX-first pattern itself is unchanged.

Consequences

Section titled “Consequences”
  • Routing and handlers are easy to follow and extend.
  • UI updates are efficient and minimize client JS.
  • Error handling is consistent and user-friendly.

Enforcement

Section titled “Enforcement”
  • Testable consequences:
    • TC-1: Chi is the router in use.
  • Checks:
    • TC-1 → go build in task ci — removing chi breaks the server package (status: block, pre-existing)
  • Not machine-checkable: Handler focus/size, RESTful naming, “Alpine only where server-side can’t” — all semantic judgment enforced in review.
  • Graduation log: (empty)