Skip to content

CLAUDE.md

Latest commit

 

History

History
56 lines (42 loc) · 3.49 KB

CLAUDE.md

File metadata and controls

56 lines (42 loc) · 3.49 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

"Teamwork" — a 28-chapter HTMX course that builds a collaborative task board. The course uses Gleam as the backend language; chapters are markdown files with embedded code blocks (no separate runnable source code repo).

Tech stack taught in the course:

  • Backend: Gleam + Wisp (web framework) + Mist (HTTP server)
  • HTML generation: Lustre (type-safe HTML DSL) + hx library (typed HTMX attributes for Lustre)
  • Interactivity: HTMX 2.0.8, _hyperscript (companion scripting language)
  • Database: SQLite via sqlight
  • Concurrency: BEAM VM (Erlang/OTP runtime), OTP actors
  • Testing: gleeunit, wisp/simulate for integration tests

Repository Structure

01-beginner/              Chapters 1–6: HTTP basics, Mist/Wisp setup, Lustre HTML, first HTMX interactions, server state
02-intermediate/          Chapters 7–12: Forms, validation, swap strategies, search/filters, navigation, auth/sessions
03-advanced/              Chapters 13–18: SSE, security, testing, extensions, deployment, third-party JS (Flatpickr)
04-real-world-patterns/   Chapters 19–28: Error handling, response headers, inline editing, modals, _hyperscript, dynamic forms, file uploads, accessibility, DB performance, background jobs
05-appendices/            A1 (bibliography & resources), A2 (_hyperscript reference), A3 (installing mise)

Chapters are sequential and cross-reference each other with relative markdown links (e.g., [Chapter 9](../02-intermediate/09-swap-strategies-and-targets.md)). Same-folder links use just the filename; cross-folder links use ../target-folder/filename.md. Every "Chapter X" and "Appendix X" mention in prose is a clickable link (except title headings and code comments).

Each chapter follows this structure: learning objectives → theory → code walkthrough → full code listing → exercises → solution hints → key takeaways → what's next.

Writing Conventions

  • All code examples use Gleam with these libraries at these version ranges:
    • wisp >= 2.0.0 < 3.0.0, mist >= 5.0.0 < 6.0.0, lustre >= 5.0.0 < 6.0.0, hx >= 3.0.0 < 4.0.0
    • gleam_stdlib >= 0.50.0, gleam_http >= 4.0.0, gleam_erlang >= 1.0.0, gleam_otp >= 1.0.0
  • The hx library provides typed HTMX attributes: hx.get(), hx.target(hx.Selector("#id")), hx.swap(hx.InnerHTML), hx.trigger([...]), hx.push_url(True), etc.
  • Lustre HTML uses html.div(attrs, children) pattern; render with element.to_document_string() (full page) or element.to_string() (fragment).
  • Routing uses Wisp's wisp.path_segments(req) pattern-matching style.
  • Form data accessed via use form_data <- wisp.require_form(req) then list.key_find(form_data.values, "field_name").
  • State management uses BEAM actors: actor.new(state) |> actor.on_message(handler) |> actor.start.

API Correctness

All 28 chapters have been verified against a 14-pattern grep sweep for API correctness. See the auto-memory files api-reference.md and review-progress.md for verified API signatures and common pitfalls. When editing chapters, maintain correct API usage for Wisp, Lustre, hx, and sqlight.

Key Documentation References

Library Docs
HTMX htmx.org
Gleam gleam.run (includes interactive tour)
Wisp hexdocs.pm/wisp/
Mist hexdocs.pm/mist/
Lustre hexdocs.pm/lustre/
hx hexdocs.pm/hx/
_hyperscript hyperscript.org