# CLAUDE.md

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

## Build & Test Commands

```bash
# Build (skip tests)
mvn clean package -DskipTests

# Run all tests
mvn clean test

# Run a single test class
mvn test -Dtest=ChargebeeServiceTest

# Run a single test method
mvn test -Dtest=ChargebeeServiceTest#testMethodName

# Generate code coverage report (output: target/jacoco-ut/index.html)
mvn clean test jacoco:report

# Run with Spring Boot plugin
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=development"
```

Server runs on port **8094**.

## Architecture Overview

This is a **Spring Boot 3.4.5 / Java 21** billing microservice for NetFoundry. It manages subscriptions, usage metering, and invoicing across two billing providers.

### Package Structure (`io.netfoundry.billing`)

- **`controller/`** — REST endpoints (HATEOAS responses, Spring RestDocs)
- **`domain/`** — Core business logic organized by subdomain:
  - `subscription/` — Enterprise, SelfService, and Trial subscription types
  - `usage/` — Usage tracking, metering, and end-of-month reporting
  - `overage/` — Metered overage management
  - `invoice/`, `contract/`, `paymentprofile/`, `accounthierarchy/`
  - `billableresource/` — Networks, Gateways, Endpoints, Data (GB), Support tiers
- **`processor/`** — Spring Batch processors for async operations (usage metering, onboard/offboard, upgrades, consistency checks)
- **`chargebee/`** — Chargebee integration for self-service subscriptions
- **`external/netsuite/`** — NetSuite ERP integration for enterprise subscriptions
- **`config/`** — Spring configuration (security, scheduling, RabbitMQ, Elasticsearch, AWS Secrets Manager)

### Key External Integrations

| System | Purpose |
|--------|---------|
| **Chargebee** | Self-service subscription billing |
| **NetSuite** | Enterprise ERP (subscriptions, usage records, pricing) |
| **Elasticsearch** | Usage data retrieval and metrics export |
| **RabbitMQ** | Async batch processing (`processing.executor.type=rabbit`) |
| **Redis** | Distributed process tracking and locks |
| **AWS Secrets Manager** | Runtime credential injection (`aws.secretsmanager.name=billing`) |

### Data Layer

- **MySQL 8** with **Flyway** migrations (`src/main/resources/database/migration/`)
- **Spring Data JDBC** (not JPA) for data access
- **ShedLock** for distributed scheduled task locking

### Testing Infrastructure

- **H2 in-memory** (PostgreSQL compatibility mode) for tests
- Test migrations in `src/main/resources/database/testmigration/`
- **WireMock** for stubbing external HTTP calls
- **Spring RestDocs** generates API docs from tests (`target/generated-snippets/`)

### Subscription Model

There are three subscription types: Enterprise (NetSuite-backed), SelfService (Chargebee), and Trial. Billable items include Networks, Gateways, Endpoints, Data (GB), and Support tiers. Usage is tracked daily and metered at month-end.

### Async Processing

Batch operations use a **process framework** backed by RabbitMQ (executor) and Redis (tracker). Concurrency is 10–50 consumers (`processing.executor.rabbit.concurrency=10-50`). Scheduled tasks use `@Scheduled` with ShedLock to prevent duplicate execution across instances.