Add CLAUDE.md with project architecture and development commands

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-14 12:03:38 +01:00
parent c3b2efd68c
commit 07b442a579
1 changed files with 92 additions and 0 deletions
@@ -0,0 +1,92 @@
+# 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`.