CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Structure
6 
7```
8core/
9├── dotCMS/                          # Main backend Java code
10│   └── src/main/java/com/
11│       ├── dotcms/                  # Modern domain-driven packages (prefer these)
12│       └── dotmarketing/            # Legacy packages (15+ yr old code, still active)
13├── core-web/                        # Frontend (Angular/Nx monorepo) → see core-web/CLAUDE.md
14├── dotcms-integration/              # Integration tests
15├── dotcms-postman/                  # Postman API tests
16├── bom/application/pom.xml          # Dependency versions (ONLY place for versions)
17├── parent/pom.xml                   # Plugin management
18└── .github/workflows/               # CI/CD pipelines
19```
20 
21## Environment Prerequisites
22 
23```bash
24sdk env install   # Java 25 via SDKMAN (.sdkmanrc) — build fails with wrong version
25nvm use           # Node 22.15+ via nvm (.nvmrc) — frontend build fails with wrong version
26```
27 
28## Build & Test Commands
29 
30```bash
31# Build (choose based on scope)
32./mvnw install -pl :dotcms-core --am -DskipTests          # Core + in-project deps (~2-3 min) ✅
33./mvnw install -pl :dotcms-core -DskipTests                # ⚠️ Can fail: missing in-project deps
34./mvnw clean install -DskipTests                            # Full rebuild (~8-15 min)
35./mvnw clean install -DskipTests -Ddocker.skip             # Full rebuild, skip Docker image
36 
37# Test (⚠️ NEVER run full integration suite — 60+ min)
38./mvnw verify -pl :dotcms-integration -Dcoreit.test.skip=false -Dit.test=MyTestClass        # Specific class
39./mvnw verify -pl :dotcms-integration -Dcoreit.test.skip=false -Dit.test=MyTest#testMethod  # Specific method
40./mvnw verify -pl :dotcms-postman -Dpostman.test.skip=false -Dpostman.collections=all       # Postman
41 
42# IDE Testing (fastest iteration)
43just test-integration-ide     # Start PostgreSQL + Elasticsearch + dotCMS
44just test-integration-stop    # Stop services when done
45 
46# Run
47just dev-run                         # Start dotCMS in Docker with Glowroot
48cd core-web && yarn nx serve dotcms-ui   # Frontend dev server only (use yarn nx, not nx)
49```
50 
51> All test modules need explicit `skip=false` flags or tests are silently skipped.
52 
53## Essential Java Patterns
54 
55```java
56import com.dotmarketing.util.Config;        // Config.getStringProperty("key", "default")
57import com.dotmarketing.util.Logger;        // Logger.info(this, "message")
58import com.dotmarketing.util.UtilMethods;   // UtilMethods.isSet(value)
59UserAPI userAPI = APILocator.getUserAPI();   // Service access pattern
60```
61 
62> **Batch permission filtering**: prefer `permissionAPI.filterCollection(Collection<P>, int, User, boolean)` over per-item `doesUserHavePermission` loops — one SQL round-trip vs N. See [Java Standards → Permission Checks](docs/backend/JAVA_STANDARDS.md#permission-checks--batch-vs-scalar).
63 
64## Critical Rules
65 
66- **Config/Logger only**: Never `System.out`, `System.getProperty`, or `System.getenv`
67- **Maven versions**: Add to `bom/application/pom.xml` ONLY, never `dotCMS/pom.xml`
68- **Java version**: Core modules compile to Java 25 by default (`dotcms.core.compiler.release`; override e.g. `-Ddotcms.core.compiler.release=11` for older bytecode). Java 25 runtime. CLI may target lower for portability.
69- **Security**: No hardcoded secrets, validate all input, never log sensitive data
70- **REST @Schema**: Must match actual return type — see [REST API Guide](dotCMS/src/main/java/com/dotcms/rest/CLAUDE.md)
71- **Frontend**: See [core-web/CLAUDE.md](core-web/CLAUDE.md) for Angular/TypeScript standards
72 
73### OpenAPI / Swagger
74 
75`openapi.yaml` is **auto-generated** by `swagger-maven-plugin` at compile phase — it writes directly to `src/main/webapp/WEB-INF/openapi/openapi.yaml`. The CI verifies the committed file matches what the build produces.
76 
77- All description changes must go in Java `@Operation` / `@Parameter` annotations, not in the yaml directly
78- Regenerate after annotation changes: `./mvnw compile -pl :dotcms-core -DskipTests` (no Docker needed)
79- Commit the regenerated yaml alongside the Java changes
80 
81### Progressive Enhancement
82 
83When editing ANY code, improve incrementally:
84- Add missing generics: `List<String>` not `List`
85- Replace legacy: `Logger.info()` not `System.out.println()`
86- Modern Angular: `@if` not `*ngIf`, `input()` not `@Input()`
87- Add missing annotations: `@Override`, `@Nullable`
88 
89## Tech Stack
90 
91- **Backend**: Java 25 (runtime + core compile target, override-able), Maven, Spring/CDI
92- **Frontend**: Angular 21+, Nx, PrimeNG, Tailwind CSS, Jest/Spectator — [core-web/CLAUDE.md](core-web/CLAUDE.md)
93- **Infrastructure**: Docker, PostgreSQL, Elasticsearch, GitHub Actions
94 
95## Documentation (Load On-Demand)
96 
97### Core Architecture & Workflows
98- [Architecture Overview](docs/core/ARCHITECTURE_OVERVIEW.md) — System design, modules, patterns
99- [Git Workflows](docs/core/GIT_WORKFLOWS.md) — Branch naming, PR process, conventional commits
100- [CI/CD Pipeline](docs/core/CICD_PIPELINE.md) — Build process, testing, deployment
101- [Security Principles](docs/core/SECURITY_PRINCIPLES.md) — Input validation, secrets, logging
102- [GitHub Issue Management](docs/core/GITHUB_ISSUE_MANAGEMENT.md) — Issues, PRs, epics
103- [Rollback-Unsafe Change Categories](docs/core/ROLLBACK_UNSAFE_CATEGORIES.md) — DB schema, ES mapping, API contract risks
104 
105### Backend Development (Java/Maven)
106- [Java Standards](docs/backend/JAVA_STANDARDS.md) — Coding patterns, immutables, exceptions, utilities
107- [REST API Patterns](docs/backend/REST_API_PATTERNS.md) — JAX-RS, Swagger, @Schema rules
108- [Maven Build System](docs/backend/MAVEN_BUILD_SYSTEM.md) — Dependency management
109- [Configuration Patterns](docs/backend/CONFIGURATION_PATTERNS.md) — Config.getProperty() usage
110- [Database Patterns](docs/backend/DATABASE_PATTERNS.md) — DotConnect, transactions
111- [Health Monitoring](docs/backend/HEALTH_MONITORING.md) — Health endpoints, log levels
112 
113### Frontend Development (Angular/TypeScript)
114- [Angular Standards](docs/frontend/ANGULAR_STANDARDS.md) — Modern syntax, signals, components
115- [Testing Frontend](docs/frontend/TESTING_FRONTEND.md) — Spectator patterns, Jest config
116- [Component Architecture](docs/frontend/COMPONENT_ARCHITECTURE.md) — Structure, organization
117- [Styling Standards](docs/frontend/STYLING_STANDARDS.md) — SCSS, BEM, Tailwind
118 
119### Testing
120- [Backend Unit Tests](docs/testing/BACKEND_UNIT_TESTS.md) — JUnit, integration patterns
121- [Integration Tests](docs/testing/INTEGRATION_TESTS.md) — API testing, database setup
122- [E2E Tests](docs/testing/E2E_TESTS.md) — Playwright, user workflows
123 
124### Infrastructure
125- [Docker Build Process](docs/infrastructure/DOCKER_BUILD_PROCESS.md) — Container setup, optimization
126 
127## Context Management
128 
129### For Claude
130- Use this guide for always-available context
131- Load `/docs/` files on-demand with Read tool
132- Use `/clear` between different work contexts
133 
134### For Cursor
135- Project rules: `.cursor/rules/` (`.mdc` files with globs); see `.cursor/rules/README.md`
136- Use `@docs/path/file.md` syntax for detailed patterns
137- Domain-specific rules load by file pattern (Java, Angular, tests, docs)
138 
139## Documentation Maintenance
140 
141- **CLAUDE.md**: Navigation hub + essential quick-reference only
142- **`/docs/`**: Full patterns by domain — single source of truth
143- **`.cursor/rules/`**: Short reminders with globs, link to `/docs/`
144- When patterns are missing: update the relevant `/docs/{domain}/` file, not this file
145