# CLAUDE.md

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

## Build & Run Commands

```bash
# Build
./mvnw clean install

# Build without tests
./mvnw clean install -DskipTests

# Run all tests
./mvnw test

# Run a single test class
./mvnw test -Dtest=NetworkComponentUsageServiceTest

# Run a single test method
./mvnw test -Dtest=NetworkComponentUsageServiceTest#methodName

# Start local MySQL (required for local dev)
docker-compose up -d

# Run locally (port 8079)
./run.sh

# SonarCloud analysis
./sonar.sh
```

## Architecture Overview

Spring Boot 3.4.5 / Java 21 microservice that tracks entitlement usage for NetFoundry's zero-trust networking platform. It coordinates across multiple external services to compute billable resource counts and stream usage data.

**Core processing flow:**

```
NetworkComponentUsageProcessor
  → Billing Service    (subscriptions, billable resources)
  → Core Service       (networks, endpoints, edge routers)
  → Ziti Controller    (v8 network identities and routers)
  → produces usage documents
      → Kinesis stream (nf-entitlement-metering)
      → Elasticsearch  (for query/aggregation)
  → exposed via UsageController REST API
```

**Main source tree** (`src/main/java/io/netfoundry/entitlement/`):

| Package | Responsibility |
|---|---|
| `processor/usage/` | `NetworkComponentUsageProcessor` — core business logic; fetches subscriptions, resolves billable resources, collects v7/v8 network components |
| `domain/usage/` | Service layer (`NetworkComponentUsageService`, `NetworkDataUsageService`) and domain models; writes to Kinesis, reads from Elasticsearch |
| `controller/` | REST endpoints (`/network-component-usages` AVERAGE, `/network-data-usages` SUM); global exception handler in `advice/` |
| `ziti/` | Reads identities and edge routers from Ziti Controller; Redis-based caching via `RedissonCacheManager` |
| `config/` | Spring config for Auth0, MySQL, Elasticsearch, Ziti, scheduling |
| `util/` | `Retry`/`RetryConfig` — configurable backoff; `ClientUtils` — REST client helpers |
| `exception/` | `DataNotFoundException` |

**Plan types handled by the processor:** self-service, enterprise, trial (internal), MSP (internal).

**Network architecture versions:**
- v7 — traditional NetFoundry APIs (Core Service)
- v8 — Ziti-native APIs (Ziti Controller + `ZitiReaderService`)

## Key External Dependencies

| Service | Default port | What it provides |
|---|---|---|
| Auth Service | `:8095` | Token/identity management |
| Core Service v2/v3 | `:9300` | Networks, endpoints, edge routers |
| Billing Service | `:8094` | Subscriptions, billable resources, billing accounts |
| Data Service | `:8088` | Data analytics |
| Ziti Controller | configured | Identities and edge routers for v8 networks |
| MySQL | `:3314` (local via docker-compose on `:3340`) | Relational data; Flyway migrations in `db/migration/` |
| Redis | `:6379` | Caching + ShedLock distributed scheduler locking |
| Elasticsearch | configured | Usage document store |
| AWS Kinesis | `nf-entitlement-metering` stream | Usage event streaming |

## Configuration Profiles

`application.properties` is the base; environment-specific overrides live in `application-{development,staging,sandbox,production}.properties`. Active profile is set via `SPRING_PROFILES_ACTIVE`. Service URLs follow the pattern `io.netfoundry.{auth,core,billing,data}.serviceurl`.

## Testing Approach

Tests use JUnit 5 + Mockito + Spring Boot Test. `ServerTestConfiguration` and `AuthorizationTestConfiguration` in `src/test/java/` provide test-specific beans (no real Auth0 required in tests). Integration tests that exercise the full Spring context are annotated `@SpringBootTest`.