Adding basic CLAUDE.md

We will edit it as needed

Author: andrus

CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Apache Cayenne is a Java ORM and persistence framework. This is a multi-module Maven project (22 modules) targeting Java 11+.
+
+## Build Commands
+
+```bash
+# Full build
+mvn clean verify
+
+# Skip tests
+mvn clean verify -DskipTests
+
+# Build a single module and its dependencies
+mvn clean verify -pl cayenne -am
+```
+
+## Testing
+
+The `cayenneTestConnection` property selects the database backend for tests. Default is HSQL.
+
+```bash
+# Run all tests (HSQL)
+mvn verify
+
+# Run against specific databases
+mvn verify -DcayenneTestConnection=h2
+mvn verify -DcayenneTestConnection=derby
+mvn verify -DcayenneTestConnection=mysql-tc        # via TestContainers
+mvn verify -DcayenneTestConnection=postgres-tc      # via TestContainers
+mvn verify -DcayenneTestConnection=sqlserver-tc     # via TestContainers
+
+# Run a single test class (in the relevant module directory)
+mvn test -Dtest=PoolingDataSourceTest
+
+# Run a single test method
+mvn test -Dtest=PoolingDataSourceTest#testConnection
+
+# Run a single test against a specific database
+mvn test -Dtest=SomeTest -DcayenneTestConnection=h2
+```
+
+CI runs JDK 11 and 17 with all database profiles on each PR.
+
+## Module Structure
+
+- **cayenne** — Core ORM library (main module to work with)
+- **cayenne-di** — Lightweight DI container used internally
+- **cayenne-project** — Cayenne project/model file management
+- **cayenne-cgen** — Code generation from database schemas
+- **cayenne-dbsync** — Database schema synchronization
+- **cayenne-gradle-plugin**, **maven-plugins**, **cayenne-ant** — Build tool integrations
+- **cayenne-crypto**, **cayenne-commitlog**, **cayenne-lifecycle**, **cayenne-jcache**, **cayenne-cache-invalidation** — Optional extension modules
+- **modeler** — CayenneModeler GUI application (Swing)
+
+## Architecture
+
+### Core Abstractions
+
+- **`CayenneRuntime`** — Entry point; manages lifecycle and wires together all components via `cayenne-di`
+- **`ObjectContext`** — Primary user-facing API for CRUD operations; tracks object changes and commits transactions
+- **`DataChannel`** / **`DataDomain`** — Sits between `ObjectContext` and the database; routes queries and manages caching
+- **`DataNode`** — Represents a physical database connection (datasource + adapter)
+- **`DbAdapter`** — Database-specific SQL generation; implementations in `org.apache.cayenne.dba.*` (MySQL, PostgreSQL, Oracle, etc.)
+
+### Query API
+
+- **`ObjectSelect`** — Modern fluent API for fetching persistent objects (preferred)
+- **`SQLSelect`** / **`SQLExec`** — Raw SQL with Cayenne parameter binding
+- **`EJBQLQuery`** — Legacy EJBQL support
+- **`Expression`** / **`ExpressionFactory`** — In-memory and SQL predicate building
+
+### ORM Mapping
+
+- Mapping metadata lives in `cayenne-project.xml` (project descriptor) and `*.map.xml` files (per-DataMap); loaded at startup into `DataMap` / `EntityResolver`
+- `ObjEntity` → Java class; `DbEntity` → database table; `ObjRelationship` / `DbRelationship` → joins
+- Persistent classes extend `_Abstract*` superclasses generated by `cayenne-cgen`; user subclasses those
+
+### Key Packages (inside `cayenne/src/main/java/org/apache/cayenne/`)
+
+| Package | Purpose |
+|---|---|
+| `access/` | Database access layer, `DataDomain`, `DataContext` |
+| `configuration/` | Runtime bootstrap, XML config loading |
+| `query/` | All query types |
+| `exp/` | Expression/criteria parsing and evaluation |
+| `dba/` | Per-database SQL dialects and adapters |
+| `map/` | ORM mapping metadata (`DataMap`, `ObjEntity`, etc.) |
+| `runtime/` | `CayenneRuntime`, DI module wiring |
+| `tx/` | Transaction management |
+
+### Test Infrastructure
+
+Tests in `cayenne/src/test/` use a shared set of test mapping files and database scripts in `src/test/resources/`. The `DBHelper` and `UnitDbAdapter` utilities handle database-specific test setup. TestContainers is used for non-embedded databases.