93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# 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`.
|