# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

### Build
```bash
./mvnw clean package -DskipTests
./mvnw clean install -DskipTests
```

### Run all tests
```bash
./mvnw test
```

### Run a single test class
```bash
./mvnw test -Dtest=AppWanControllerV2Test
```

### Run tests by tag
```bash
./mvnw test -Dgroups=controller_v2
./mvnw test -Dgroups=controller_services
```

### Run the application locally
```bash
./mvnw spring-boot:run -Dspring-boot.run.profiles=development
# or
./run.sh
```

### SonarCloud analysis
```bash
./sonar.sh
```

## Architecture

### Package layout

All production code lives under `src/main/java/io/netfoundry/core/`:

| Package | Role |
|---|---|
| `controller/` | REST endpoints (Spring MVC). One controller per resource type, with `V2`/`V3` variants for versioned resources. |
| `domain/<resource>/` | Per-resource subdirectory: entity POJO, `CreateXxx`/`UpdateXxx` DTOs, `XxxService` (business logic), `XxxRepository` (JDBC queries), `FindXxx` (query DSL), and `XxxResourceResolver` (HATEOAS link builder). |
| `process/` | 70+ standalone `Process` classes that implement complex multi-step operations (create/update/delete workflows that touch Ziti, AWS, messaging, etc.). Called by `XxxService`. |
| `external/` | Adapters to external systems: `ziti/` (OpenZiti API client), `identity/`, `sds/`, `certs/`, `dns/`, `backup/`, `networkauth/`, `secrets/` (AWS Secrets Manager), `metadata/`. |
| `cache/` | Redisson-backed distributed cache wrappers. |
| `event/` | Resource change event publishing to RabbitMQ. |
| `config/` | Spring `@Configuration` beans; `ServerConfiguration` is the main config class extended by tests. |
| `validation/` | Custom JSR-303 validators used across controllers and domain objects. |
| `cloud/` | Cloud-provider abstractions (`CloudAddressManager`) for AWS, GCP, Azure, OCI. |
| `requestversion/` | API version negotiation filter (`ApiVersionManagementFilter`) and `RequestVersionHolder`. |

### Request lifecycle

1. **Controller** (`controller/XxxController.java`) — validates the HTTP request, checks authorization via `@PreAuthorize` / NetFoundry auth framework, maps to a domain DTO.
2. **Service** (`domain/<resource>/XxxService.java`) — owns transactions, resolves related entities, delegates complex work to a `Process`.
3. **Process** (`process/XxxProcess.java`) — orchestrates multi-system operations: persists to MySQL via `Repository`, calls Ziti API via `external/ziti/`, publishes events via `event/`, may call AWS SDK.
4. **Repository** (`domain/<resource>/XxxRepository.java`) — raw JDBC with `WhereClauseResolver` for dynamic query building.

### API versioning

The API exposes two live versions: `v2` (`/core/v2/...`) and `v3` (`/core/v3/...`). Controllers with both versions typically share a `XxxCommonController` base class. The `ApiVersionManagementFilter` routes requests and the `RequestVersionHolder` exposes the current version to downstream code.

### Test structure

Tests inherit from a hierarchy:
- `BaseServiceTest` — `@SpringBootTest` + `@ExtendWith(MysqlCallback.class)` (Testcontainers MySQL + Redis). Full integration context.
- `ApiDocTest extends BaseServiceTest` — adds MockMvc + Spring REST Docs setup.
- `AuthenticatedApiDocTest extends ApiDocTest` — adds JWT token generation via `MockAuthEntityResolver` and helper methods (`read(uuid)`, `create(uuid)`, `update(uuid)`, `delete(uuid)`, etc.) for building `RequestPostProcessor` auth grants.

Controller tests extend `AuthenticatedApiDocTest`, mock Ziti/external service beans with `@MockitoBean`, and exercise the full Spring context against the real database. The test configurations in `src/test/java/io/netfoundry/core/config/` replace AWS, cloud, RabbitMQ, and Ziti beans with mocks/no-ops.

### Key domain concepts

- **Network** — top-level tenant boundary; most resources belong to a network.
- **Edge Router** — Ziti router; has V2 (hosted) and V3 variants, and an upgrade lifecycle.
- **Endpoint / Service / AppWan** — Ziti identities, services, and policies.
- **Container / Host** — infrastructure nodes that run network controllers or edge routers on AWS/GCP/Azure/OCI.
- **Execution** — records of async process outcomes, queryable via `ExecutionRepository`.
- **NetworkAssembly** — template/blueprint for provisioning a full network resource tree.

### Lombok

The project uses Lombok extensively (`@Value`, `@Builder`, `@Data`, `@Slf4j`, etc.). `src/main/java/io/netfoundry/core/lombok.config` configures Lombok behavior for this module.