CLAUDE.md in dotCMS/core runs 1,520 words across 24 headings.
The Visual Headless Content Management System for Enterprises
JavaCovers
11 of the 20 section tags
In the order a file is read inHeadings
24 headings, in the order the file writes them
01CLAUDE.md
02Project Structure
03Environment Prerequisites
04Build & Test Commands
05Build (choose based on scope)
06Test (⚠️ NEVER run full integration suite — 60+ min)
07IDE Testing (fastest iteration)
08Run
09Essential Java Patterns
10Critical Rules
11OpenAPI / Swagger
12Progressive Enhancement
13Spec-Driven Development (Spec-Kit)
14Tech Stack
15Documentation (Load On-Demand)
16Core Architecture & Workflows
17Backend Development (Java/Maven)
18Frontend Development (Angular/TypeScript)
19Testing
20Infrastructure
21Context Management
22For Claude
23For Cursor
24Documentation Maintenance
Commands
3 commands this file writes down
Extracted from the file, verbatimjust test-integration-ide
just test-integration-stop
just dev-run
The file
CLAUDE.md
First 160 of 177 lines1# 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 # installs the Java version pinned in .sdkmanrc — build fails with wrong version
25nvm use # installs the Node version pinned in .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 && pnpm nx serve dotcms-ui # Frontend dev server only (Nx is not global — always via pnpm)
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**: see `.sdkmanrc` for the runtime version. Core modules compile to whatever `dotcms.core.compiler.release` is set to in `parent/pom.xml` (override e.g. `-Ddotcms.core.compiler.release=11` for older bytecode); `tools/dotcms-cli` targets whatever `maven.compiler.release` is set to in its own `pom.xml`, historically 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- **Integration test registration**: A new integration test class not added to a `MainSuite*`/`Junit5Suite*` `@SuiteClasses` list compiles fine but is **silently never run in CI** (green build, zero coverage) — it only runs locally via `-Dit.test=`. See [Integration Tests → Registering Tests in a MainSuite](docs/testing/INTEGRATION_TESTS.md#registering-tests-in-a-mainsuite-ci-gate).
72- **Integration tests can silently run zero tests**: the Maven build cache may short-circuit failsafe (`Skipping plugin execution (cached): failsafe:integration-test`) — BUILD SUCCESS, `<completed>0</completed>`, exit 0. Pass `-Dmaven.build.cache.enabled=false`, prefer class-level over `-Dit.test=Class#method` selection, and confirm `Tests run: N` in `target/failsafe-reports/*.txt` rather than trusting the exit code. See [Integration Tests → The build cache can skip the tests entirely](docs/testing/INTEGRATION_TESTS.md#the-build-cache-can-skip-the-tests-entirely).
73- **Frontend**: See [core-web/CLAUDE.md](core-web/CLAUDE.md) for Angular/TypeScript standards
74
75### OpenAPI / Swagger
76
77`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.
78
79- All description changes must go in Java `@Operation` / `@Parameter` annotations, not in the yaml directly
80- Regenerate after annotation changes: `./mvnw compile -pl :dotcms-core --am -DskipTests` (no Docker needed; `--am` avoids the same missing-in-project-deps failure noted above)
81- Commit the regenerated yaml alongside the Java changes
82
83### Progressive Enhancement
84
85When editing ANY code, improve incrementally:
86- Add missing generics: `List<String>` not `List`
87- Replace legacy: `Logger.info()` not `System.out.println()`
88- Modern Angular: `@if` not `*ngIf`, `input()` not `@Input()`
89- Add missing annotations: `@Override`, `@Nullable`
90- Add missing Javadoc on any Java method you edit, human-readable not AI-oriented — see [Java Standards → Javadoc Requirements](docs/backend/JAVA_STANDARDS.md#javadoc-requirements-required)
91
92## Spec-Driven Development (Spec-Kit)
93
94This repo uses [GitHub Spec-Kit](https://github.com/github/spec-kit) for spec-driven work,
95customized for dotCMS. How to run it: [Spec-Kit Quick Start](docs/core/SPEC_KIT_QUICK_START.md).
96How it's built + upgrade re-apply notes: [.specify/CUSTOMIZATIONS.md](.specify/CUSTOMIZATIONS.md).
97
98- **Flow**: `/speckit-specify` (new feature) **or** `/speckit-specify-fix` (issue/bug resolution) → **PR 1 (spec) approved** → `/speckit-plan` → `/speckit-tasks` → `/speckit-implement` → `/speckit-converge` → PR 2 (implementation).
99- **Two PRs, gated on approval — not merge**: PR 1 carries `spec.md` **alone** and another dev must **approve** it before `/speckit-plan` runs. Do **not** wait for PR 1 to merge — branch off the spec branch (the spec isn't on `main` yet) and open PR 2 with the implementation. If the spec changes after sign-off, get it re-approved. **Before opening PR 2, run `/speckit-converge` on your final code** and get `converged` (or consciously accept what remains). Human-triggered and human-judged; nothing enforces it. See [Quick Start §3](docs/core/SPEC_KIT_QUICK_START.md).
100- **Constitution**: [.specify/memory/constitution.md](.specify/memory/constitution.md) — legacy-awareness + Critical Rules; loaded by every skill.
101- **TDD (Principle V, non-negotiable)**: no implementation code before tests are written, **dev-approved**, and confirmed **failing (Red)**. If a test type can't be done, the dev must say so and why. Enforced in the constitution + `tasks-template` `[GATE]` tasks + plan Test Strategy.
102- **Convergence (closing step — you trigger it)**: `/speckit-converge` checks the code against the approved spec. `/speckit-implement` **recommends** it on finishing (`after_implement` hook, `optional: true`) but does **not** run it — the end of the task list is rarely the end of your work, and a run fired before your manual corrections would assess code you're about to change. Run it when you judge the work done, fix, repeat until `converged`. **Append-only** — findings become tasks in `tasks.md`, never direct edits. See [Quick Start §9](docs/core/SPEC_KIT_QUICK_START.md).
103- **ADRs**: live only in the private repo `dotCMS/platform-adrs`. `/speckit-plan` **always consults** relevant ADRs (auto `before_plan` hook → `/speckit-adr-context`, read-only via `gh`). Spec-Kit **never creates ADRs** — it only *proposes* them; ADRs are authored in `platform-adrs` via its `new-adr.sh`.
104
105## Tech Stack
106
107- **Backend**: Java (see `.sdkmanrc` / `parent/pom.xml`'s `dotcms.core.compiler.release`, override-able), Maven, CDI
108- **Frontend**: Angular (see `core-web/package.json`'s `@angular/core`), Nx, PrimeNG, Tailwind CSS, Jest/Spectator — [core-web/CLAUDE.md](core-web/CLAUDE.md)
109- **Infrastructure**: Docker, PostgreSQL, Elasticsearch, GitHub Actions
110
111## Documentation (Load On-Demand)
112
113### Core Architecture & Workflows
114- [Architecture Overview](docs/core/ARCHITECTURE_OVERVIEW.md) — System design, modules, patterns
115- [Git Workflows](docs/core/GIT_WORKFLOWS.md) — Branch naming, PR process, conventional commits
116- [CI/CD Pipeline](docs/core/CICD_PIPELINE.md) — Build process, testing, deployment
117- [Security Principles](docs/core/SECURITY_PRINCIPLES.md) — Input validation, secrets, logging
118- [GitHub Issue Management](docs/core/GITHUB_ISSUE_MANAGEMENT.md) — Issues, PRs, epics
119- [Rollback-Unsafe Change Categories](docs/core/ROLLBACK_UNSAFE_CATEGORIES.md) — DB schema, ES mapping, API contract risks
120
121### Backend Development (Java/Maven)
122- [Java Standards](docs/backend/JAVA_STANDARDS.md) — Coding patterns, immutables, exceptions, utilities
123- [When to Use Virtual Threads](docs/backend/VIRTUAL_THREADS.md) — Socket I/O yes, file I/O no; carrier pinning
124- [REST API Patterns](docs/backend/REST_API_PATTERNS.md) — JAX-RS, Swagger, @Schema rules
125- [Maven Build System](docs/backend/MAVEN_BUILD_SYSTEM.md) — Dependency management
126- [Configuration Patterns](docs/backend/CONFIGURATION_PATTERNS.md) — Config.getProperty() usage
127- [Database Patterns](docs/backend/DATABASE_PATTERNS.md) — DotConnect, transactions
128- [Health Monitoring](docs/backend/HEALTH_MONITORING.md) — Health endpoints, log levels
129- [Security Patterns](docs/backend/SECURITY_BACKEND.md) — Input validation, auth, SQL/XSS prevention, secure logging
130- [Search API Migration](docs/backend/SEARCH_API_MIGRATION.md) — ES → OpenSearch: deprecated `ContentletAPI` search methods, plugin migration guide
131- [Telemetry Implementation](docs/backend/TELEMETRY_IMPLEMENTATION.md) — CDI-based metrics system, creating new metrics, `/v1/usage` endpoints
132- [Jandex Metadata Scanning](docs/backend/JANDEX_METADATA_SCANNING.md) — Fast class/annotation metadata lookup, prefer over reflection
133- **ES → OpenSearch Migration** — infra migration from ElasticSearch to OpenSearch, phased dual-write/read rollout
134 - [Migration Design](docs/backend/OPENSEARCH_MIGRATION.md) — Architecture, phased rollout, configuration
135 - [Migration Test Plan](docs/backend/OPENSEARCH_MIGRATION_TEST_PLAN.md) — QA test plan for the migration phases
136 - [Client Configuration](docs/backend/OPENSEARCH_CLIENT_CONFIGURATION.md) — `OS_*`/`ES_*` config property reference and fallback chain
137 - [Migration Tester Guide](docs/backend/OPENSEARCH_MIGRATION_TESTER_GUIDE.md) — Getting-started guide for QA testers validating the migration
138- [System Events](docs/backend/SYSTEM_EVENTS.md) — Cross-node event queue: at-least-once delivery, consumer idempotency rules, payload deserialization
139
140### Frontend Development (Angular/TypeScript)
141- **[docs/frontend/README.md](docs/frontend/README.md) — index of all frontend docs and when to load each. Start here if unsure.**
142- [Angular Standards](docs/frontend/ANGULAR_STANDARDS.md) — **single source of truth**: syntax, signals, change detection, forms, icons
143- [Component Architecture](docs/frontend/COMPONENT_ARCHITECTURE.md) — Structure, file layout, data flow
144- [State Management](docs/frontend/STATE_MANAGEMENT.md) — NgRx Signal Store, rxMethod, patchState
145- [Styling Standards](docs/frontend/STYLING_STANDARDS.md) — Tailwind, PrimeNG theme, BEM, SCSS
146- [TypeScript Standards](docs/frontend/TYPESCRIPT_STANDARDS.md) — Strict types, as const, `#` private
147- [Testing Frontend](docs/frontend/TESTING_FRONTEND.md) — Writing tests: Spectator, Jest, byTestId
148- [Testing Review Rules](docs/frontend/TESTING_REVIEW_RULES.md) — Reviewing tests: violation checklist
149- [Breadcrumbs](docs/frontend/BREADCRUMBS.md) — GlobalStore breadcrumb trail
150
151### Testing
152- [Backend Unit Tests](docs/testing/BACKEND_UNIT_TESTS.md) — JUnit, integration patterns
153- [Integration Tests](docs/testing/INTEGRATION_TESTS.md) — Running/debugging tests, MainSuite registration, API testing, database setup
154- [E2E Tests](docs/testing/E2E_TESTS.md) — Playwright, user workflows
155
156### Infrastructure
157- [Docker Build Process](docs/infrastructure/DOCKER_BUILD_PROCESS.md) — Container setup, optimization
158
159## Context Management
160
17 more lines are in the file. Read the raw file.
The rest of the repository
dotCMS/core ships 20 other instruction files
.cursor/rules/java-context.mdccore-web/libs/sdk/client/CLAUDE.md.github/instructions/frontend.instructions.mdcore-web/CLAUDE.mdcore-web/apps/dotcms-ui/AGENTS.mdcore-web/apps/mcp-server/CLAUDE.mddotCMS/src/main/java/com/dotcms/rest/CLAUDE.mdtest-jmeter/CLAUDE.mdcore-web/apps/dotcms-ui-e2e/AGENTS.md.cursor/rules/doc-updates.mdc.cursor/rules/frontend-context.mdc.cursor/rules/e2e-rules.mdccore-web/libs/sdk/react/CLAUDE.mdcore-web/AGENTS.md.github/copilot-instructions.md.cursor/rules/dotcms-guide.mdc.cursor/rules/test-context.mdccore-web/libs/block-editor/CLAUDE.mdcore-web/libs/new-block-editor/CLAUDE.mdcore-web/libs/portlets/CLAUDE.md
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs dotCMS/core can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.