# CLAUDE.md

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

## Build & Development Commands

```bash
# 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

```clojure
(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`.