Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (50 loc) · 2.79 KB

AGENTS.md

File metadata and controls

74 lines (50 loc) · 2.79 KB

AGENTS.md

Cursor Cloud specific instructions

Overview

OrderFlow Commerce is a monorepo with two services:

Service Path Tech Dev Port
API (backend) api/ Spring Boot 3.2 / Java 21 / Maven 8080
Web (frontend) web/ React 19 / Vite 8 / TypeScript 5173

Infrastructure (PostgreSQL 15, RabbitMQ 3) runs via Docker Compose.

Starting infrastructure

sudo dockerd &>/tmp/dockerd.log &   # if Docker daemon is not already running
sudo docker compose up -d postgres rabbitmq

Wait for both containers to become healthy before starting the API.

Running the API locally

The default application.properties uses Docker Compose hostnames (postgres, rabbitmq). For local dev outside Docker, use the local Spring profile (which reads application-local.properties with localhost hostnames):

cd api && ./mvnw spring-boot:run -Dspring-boot.run.profiles=local

Running the Web frontend

cd web && npm run dev

Vite proxies /api requests to http://localhost:8080 (see vite.config.ts).

Tests and Lint

  • API tests: cd api && ./mvnw test
  • Web lint: cd web && npm run lint
  • Web build: cd web && npm run build

Key endpoints when running

Full Docker development (with hot reload)

sudo docker compose up --build

This starts all services with hot reload enabled:

  • API: dev-entrypoint.sh uses inotifywait to watch src/ for .java/.properties/.xml changes, triggers mvn compile, and DevTools auto-restarts the app (~0.5s).
  • Web: Runs Vite dev server (not nginx) with full HMR via volume-mounted source files.
  • Debug port: JDWP on port 5005 (controlled by SPRING_BOOT_JVM_ARGS env var).

The vite.config.ts reads API_PROXY_TARGET env var (defaults to http://localhost:8080). In Docker Compose it's set to http://app:8080.

Non-obvious notes

  • Security is currently set to permitAll() — no auth required for any endpoint.
  • The mvnw wrapper must be chmod +x before first use (it's committed without execute bit).
  • Hibernate ddl-auto=update auto-creates schema on first run — no migration step needed.
  • The application-local.properties file (added for Cloud dev) overrides DB/RabbitMQ hosts to localhost. If you need to run the API inside Docker Compose, use -Dspring-boot.run.profiles=docker instead.
  • spring-boot-devtools is enabled: the API auto-restarts on class changes, but not on pom.xml changes.
  • The original web/Dockerfile is for production (build + nginx). web/Dockerfile.dev is for development with HMR.