# CLAUDE.md

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

## Overview

NetFoundry Identity Service — a Spring Boot 3.4.4 microservice (Java 21) managing user/service/API identities, organizations, realms, OIDC configuration, and identity providers (Auth0, AWS Cognito). Runs on port 8091.

## Commands

```bash
# Build & test
./install.sh              # mvn clean install with test profile

# Run locally (development profile, MySQL on localhost:3306/identity)
./run.sh

# Single test
./mvnw test -Dtest=ClassName#methodName

# All tests directly
./mvnw clean test

# SonarCloud analysis
./sonar.sh
```

## Architecture

**Package root**: `io.netfoundry.identity`

- `controller/` — 26 REST controllers. Named by entity (e.g., `UserIdentityController`, `OrganizationController`, `OidcIssuerController`). Login/invitation flows have dedicated flow controllers.
- `domain/` — All business logic, organized by subdomain:
  - `identity/` — `UserIdentity`, `ServiceIdentity`, `ApiAccountIdentity`; each has its own service + repository
  - `organization/` — multi-tenancy; org preferences, default roles
  - `oidc/` — issuers, public clients, audiences, and their org/user mappings
  - `idprovider/` / `idptype/` — Auth0 integration; identity provider CRUD
  - `invitation/` — user/org invitation lifecycle (default 168-hour expiry)
  - `realm/` — multi-realm support; default realm is the Netfoundry realm UUID
  - `preference/` — per-user and per-org preferences
  - `util/` — shared domain helpers
- `external/` — third-party clients: Auth0 Management API, AWS Cognito, AWS S3, Zendesk, email (Simple Java Mail)
- `config/` — Spring configuration beans

**Database**: MySQL 8.4 (production), H2 (tests). 80+ Flyway migrations in `src/main/resources/database/migration/`. Seed data in `database/init/nf-administrative-seed.sql`.

**Configuration profiles**: `development`, `production`, `staging`, `sandbox`, `integration`, `trial`, `docker`. Active profile is set by the startup scripts. Test profile disables scheduling and switches to H2.

## Testing

- Base class for unit/integration tests: `IdentityServerBaseTest`
- API documentation tests extend `ApiDocTest<R>` with `MockAuthEntityResolver`
- Email testing uses GreenMail; S3 testing uses S3Mock
- REST Docs auto-generates API docs from tests → `target/generated-docs/index.html`

## Key External Integrations

| Integration | Purpose |
|---|---|
| Auth0 | Primary user auth, MFA, user management |
| AWS Cognito | API account identity pools |
| AWS S3 | Branding asset storage |
| Zendesk | Support ticket creation |
| NetFoundry Authorization Client | Permission checks on org data |

## Notes

- The `@ApiAccountIdentity` path uses Cognito user pools directly; `@UserIdentity` and `@ServiceIdentity` route through Auth0.
- Organization data returned to callers without read permission is intentionally minimal (see `MOP-26413`).
- Branding writes/reads are realm-scoped; the default realm label is significant — adding it incorrectly causes branding to land in the wrong place (see `MOP-26407`).
- Logo resets handle one logo at a time, not both simultaneously (see `MOP-26368`/`MOP-26401`).