# CLAUDE.md

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

## Commands

```bash
# Build and run all tests
mvn clean install

# Run the service locally (requires local MySQL from docker-compose)
docker-compose up -d   # start MySQL
./run.sh               # or: mvn spring-boot:run

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

# Run a single test method
mvn test -Dtest=ClassName#methodName

# Code quality / SonarCloud
./sonar.sh

# OWASP dependency vulnerability scan
mvn verify -Pdependency_check
```

**Requirements:** Java 21, Maven 3.6.0+

## Architecture

This is a **Spring Boot 3.x microservice** (port 9301, context path `/notification/v1`) that listens to alarm events and delivers notifications to configured destinations.

### Core Flow

```
AWS SQS (alarm messages)
  → ZitiAlarmSqsListener / ZitiAlarmReceiver   [rx/alarm/]
  → NotificationEngine.processTrigger()         [setting/]
  → AlarmConditionService (filter matching)     [rx/alarm/]
  → EmailTransmitter / EmailDestinationService  [tx/email/]
  → SMTP delivery
```

### Package Layout

| Package | Responsibility |
|---|---|
| `rx/` | Event ingestion — SQS listeners, trigger/condition framework |
| `rx/alarm/` | Alarm-specific trigger, condition models and services |
| `setting/` | `NotificationSetting` domain: the persistent rule binding trigger → condition → destination; `NotificationEngine` orchestrates processing |
| `tx/` | Delivery — abstract `Transmitter`/`Destination` interfaces |
| `tx/email/` | Concrete email delivery via SMTP; Velocity templates in `resources/templates/Email/` |
| `restapi/` | REST controllers, Auth0 JWT auth, request interceptors |
| `metadata/` | Feign clients: `NetworkClient` (Core service :9300), `IdentityClient` (Auth service :8095) |
| `config/` | Spring `@Configuration` classes for DB, AWS, auth, web |
| `core/` | Resource path parsing utilities (NetFoundry resource URIs) |
| `util/` | HATEOAS helpers, CSV converters, collection utilities |

### Data Model

Three persistent entities (MySQL, no Hibernate — Spring JDBC):
- `NotificationSetting` — a rule: which trigger type + condition + destination
- `AlarmCondition` — criteria matching alarm attributes (severity, network, etc.)
- `EmailDestination` — recipient list for a setting

Schema managed by **Flyway** migrations in `src/main/resources/db/migration/`.

### External Dependencies

| System | Purpose |
|---|---|
| AWS SQS (`tf-alarms-for-notification-v7`) | Inbound alarm events |
| AWS Secrets Manager | Credential retrieval at startup |
| MySQL 8.0 (`notification` schema) | Persistence |
| NetFoundry Core service `:9300` | Network/endpoint metadata enrichment |
| NetFoundry Auth service `:8095` | Identity lookup |
| Auth0 | JWT validation for REST API |
| SMTP (`email-smtp.us-east-1.amazonaws.com:587`) | Email delivery |

### Testing

- Unit tests use **JUnit 5 + Mockito**; integration tests use an **H2 in-memory database**
- **GreenMail** provides an in-process SMTP server for email tests
- Test profile disables SQS and Secrets Manager (stubs/mocks replace real AWS clients)

### Tech Stack Notes

- **No Hibernate/JPA** — data access uses Spring JDBC directly
- **HATEOAS** responses — REST endpoints return hypermedia links
- **Apache Velocity** — email templates (not Thymeleaf/FreeMarker)
- **Spring REST Docs + SpringDoc OpenAPI** — API documentation generated during `mvn clean install`