elprice/CLAUDE.md

CLAUDE.md

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

Build & Development Commands

# Development
make run                    # Start dev server (port 3000)
make repl                   # Start nREPL
npm run css:watch           # Watch/rebuild Tailwind CSS

# Testing
make test                   # Run all tests
clj -M:test                 # Alternative

# Build
make uberjar                # Build production JAR (target/elprice-standalone.jar)
make clean                  # Remove target/

# Formatting
bb format                   # Format source with cljstyle

# Docker
docker compose up -d        # Start PostgreSQL (port 5432)

REPL Commands

(dev-prep!) (go)            ;; Start system in REPL
(reset)                     ;; Reload code and restart system
(halt)                      ;; Stop system
(migrate)                   ;; Run database migrations
(rollback)                  ;; Rollback last migration
(reset-db)                  ;; Drop and re-migrate database
;; Testing in REPL:
(test-prep!) (go) (run-tests)

Architecture

Kit framework web application: Clojure, PostgreSQL, HTMX, Hiccup, Tailwind CSS.

System Initialization

Integrant manages the component lifecycle. Configuration is in resources/system.edn, which defines components for the HTTP server (Undertow), database connection pool, migrations, routes, and middleware. The entry point is pmagnus.elprice.core, which loads the system config via pmagnus.elprice.config.

Routing

Two separate route groups registered as Integrant components:

• API routes (web/routes/api.clj) — mounted at /api, returns JSON, has Swagger docs at /api/swagger.json
• UI routes (web/routes/ui.clj) — mounted at /, returns HTML via HTMX + Hiccup

Routes are combined in web/handler.clj which builds the Ring handler with the full middleware stack.

Frontend Pattern

Server-side rendered HTML using Hiccup data structures. Interactive behavior via HTMX (no client-side JS framework). Two macros in web/htmx.clj:

• page — renders a full HTML5 document (includes Tailwind CSS and HTMX script tags)
• fragment — renders an HTML fragment for HTMX partial responses

Tailwind CSS v4 scans .clj and .html files for utility classes. Source: resources/css/input.css → Output: resources/public/css/output.css.

Database

PostgreSQL via kit-postgres and conman (connection pooling). SQL queries defined with HugSQL in resources/queries.sql. Migrations via Migratus in resources/migrations/. Migrations run automatically on system startup (migrate-on-init? true).

• Dev/Test DB: jdbc:postgresql://localhost:5432/elprice?user=elprice&password=elprice
• Prod DB: via JDBC_URL environment variable

Middleware

Defined in web/middleware/core.clj. Cookie-based sessions (http-only, same-site strict). CSRF is disabled. Static assets served from resources/public/.

Source Layout

src/clj/pmagnus/elprice/
├── core.clj                 # App entry point, system lifecycle
├── config.clj               # Integrant config loader
└── web/
    ├── handler.clj          # Ring handler + route composition
    ├── htmx.clj             # page/fragment Hiccup macros
    ├── controllers/         # Request handlers (business logic)
    ├── middleware/           # Ring middleware (core, exception, formats)
    └── routes/              # Reitit route definitions (api, ui)

Environment-specific code lives in env/{dev,prod,test}/. Dev REPL utilities are in env/dev/clj/pmagnus/elprice/user.clj.