CLAUDE.md

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

Build & Run

GitHub credentials are required for the private JClouds Maven package (hosted on GitHub Packages):

# Set credentials via environment variables
export GPR_USERNAME=<github_user>
export GPR_PASSWORD=<github_token>

# Build (skip tests)
./gradlew build -x test

# Run all tests
./gradlew test

# Run tests for a specific module
./gradlew :server:test

# Run a single test class
./gradlew :server:test --tests "com.epam.aidial.core.server.ResourceApiTest"

# Run a single test method
./gradlew :server:test --tests "com.epam.aidial.core.server.ResourceApiTest.testWorkflow"

# Checkstyle
./gradlew checkstyleMain checkstyleTest

# Run locally
./gradlew :server:run

At runtime, set AIDIAL_SETTINGS env var pointing to a JSON settings file (see sample/aidial.settings.json).

Architecture

AI DIAL Core is an HTTP reverse proxy / API gateway for LLMs built on Java 21 + Eclipse Vert.x (reactive, non-blocking). It exposes an OpenAI-compatible API and routes requests to backend AI providers (Azure OpenAI, AWS, GCP, etc.).

Gradle Modules

Key Server Sub-packages

• controller/ — HTTP request handlers (chat completions, embeddings, file upload, resource CRUD, sharing, publications, toolsets, health check)
• service/ — Business logic (ApplicationService, PublicationService, ShareService, RuleService, ToolSetService, CodeInterpreterService, …)
• security/ — JWT validation (JWKS), API key store, AES encryption service, access control
• upstream/ — Load balancing: tiered + weighted random over upstream endpoints
• limiter/ — Token-based and request-based rate limiting (per-minute/per-day per role)
• token/ — Token usage stats tracking and per-provider response parsing
• function/ — Request/response transformation middleware pipeline
• tracing/ — OpenTelemetry span processing
• config/ — Dynamic config hot-reload (FileConfigStore)

Configuration

Two config files govern the system:

• Static settings (aidial.settings.json): Vert.x server/client options, blob storage provider, Redis connection, identity providers, encryption keys, metrics endpoints. Not hot-reloaded.
• Dynamic config (aidial.config.json): models, applications, API keys, roles, interceptors, routes, toolsets, rate-limit pricing. Hot-reloaded at runtime.

See sample/ for examples of both files; server/src/main/resources/aidial.settings.json contains the built-in defaults.

Tech Stack

• Java 21, Gradle 8, Lombok (via io.freefair.lombok plugin)
• Eclipse Vert.x 4.5 — async HTTP server/client (event-loop model)
• Apache JClouds — multi-cloud blob storage
• Redisson — Redis client (caching, distributed locks)
• Jackson 2.18 — JSON serialization
• Auth0 java-jwt + jwks-rsa — JWT/JWKS authentication
• Micrometer (Prometheus + OTLP) + OpenTelemetry SDK — metrics & tracing
• JUnit 5 + Mockito 5 + Vert.x JUnit 5 — testing; integration tests start the full stack with embedded Redis and OkHttp MockWebServer for upstream simulation
• Checkstyle — Google Java Style, 180-char line limit (checkstyle/checkstyle.xml)

Code Style

Read docs/CODE_STYLE.md before writing or changing Java in this repo. It covers naming, Vert.x event-loop rules, scope discipline, error handling, completing cross-cutting changes, tests, and documentation.

Process: spec-driven with OpenSpec 1.14.3

openspec/specs/ is the behaviour reference for the parts of Core it covers; read the relevant capability before changing that code. The CLI is not installed globally. Where an OpenSpec skill or doc says openspec, run npx -y @fission-ai/openspec@1.14.3. openspec/config.yaml holds the project rules the skills and workflows follow.

1. Propose: openspec/changes/<id>/ with proposal.md, spec deltas, design.md and tasks.md, created by /opsx:propose (the openspec-propose skill) or the sdd-propose workflow. Then npx -y @fission-ai/openspec@1.14.3 validate <id> --strict.
2. Apply: implement tasks.md, ticking each task: /opsx:apply, or the sdd-apply workflow (implement, an independent verification, a three-lens review, fix).
3. Record and archive: review.md in the change folder, then npx -y @fission-ai/openspec@1.14.3 archive <id> -y, which merges the deltas into openspec/specs; then validate --specs --strict. Then one commit, staging explicit paths.

The workflows in .claude/workflows/ (sdd-baseline for specs of existing behaviour, sdd-propose, sdd-apply, and sdd-audit after a series of changes) run this with subagents.

Checks (Git Bash, from the repo root)

Gradle 8.10 needs a JDK 21 as JAVA_HOME; a newer default JDK fails with "Unsupported class file major version".

export JAVA_HOME="<path to a JDK 21>"
./gradlew checkstyleMain checkstyleTest
./gradlew :server:test --tests "com.epam.aidial.core.server.SomeApiTest"     # the classes the change touches
npx -y @fission-ai/openspec@1.14.3 validate --all --strict

Run checkstyle and the targeted test classes locally; the full suite runs in CI after the push.