Skip to content

Latest commit

 

History

History
260 lines (202 loc) · 7.91 KB

AGENTS.md

File metadata and controls

260 lines (202 loc) · 7.91 KB

CALM Hub - AI Assistant Guide

This guide helps AI assistants work efficiently with the CALM Hub backend codebase.

Tech Stack

  • Language: Java 21
  • Framework: Quarkus 3.29+ (Reactive REST, CDI)
  • Build Tool: Maven (via parent POM)
  • Databases:
    • MongoDB (production default)
    • NitriteDB (embedded, standalone mode)
  • Testing: JUnit 5, TestContainers
  • API Docs: OpenAPI/Swagger UI
  • Security: Keycloak integration (secure profile)

Key Commands

# Build & Test
../mvnw clean package                    # Full build
../mvnw -P integration verify            # Include integration tests
../mvnw test                              # Unit tests only

# Development Mode (Hot Reload)
../mvnw quarkus:dev                       # Default (MongoDB)
../mvnw quarkus:dev -Dcalm.database.mode=standalone  # Standalone (NitriteDB)
../mvnw quarkus:dev -Dquarkus.profile=secure         # Secure mode (Keycloak)

# Docker
docker-compose up                         # From deploy/ - production-like
cd local-dev && docker-compose up        # MongoDB for development

# Packaging
../mvnw package                           # Create quarkus-app/
java -jar target/quarkus-app/quarkus-run.jar  # Run packaged app

# Docker Build
docker buildx build --platform linux/amd64,linux/arm64 \
  -f src/main/docker/Dockerfile.jvm -t calm-hub --push .

Architecture Overview

Directory Structure

src/
├── main/java/org/finos/calm/
│   ├── resources/            # REST API endpoints
│   ├── services/             # Business logic
│   ├── store/                # Data access layer
│   │   ├── interfaces        # Store abstractions
│   │   ├── mongo/           # MongoDB implementations
│   │   ├── nitrite/         # NitriteDB implementations
│   │   └── producer/        # CDI producers for store selection
│   ├── domain/               # Domain models
│   └── config/               # Configuration beans
├── test/java/                # Unit tests
└── integration-test/java/    # Integration tests (TestContainers)

REST API Pattern (Quarkus JAX-RS)

@Path("/api/v1/architectures")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ArchitectureResource {
    
    @Inject
    ArchitectureService service;
    
    @GET
    public List<Architecture> listArchitectures() {
        return service.findAll();
    }
}

Storage Mode Selection

CALM Hub supports pluggable storage backends via CDI Producers:

Configuration Property: calm.database.mode (default: mongo)

Modes:

  1. mongo (default) - MongoDB production storage
  2. standalone - NitriteDB embedded storage (no external DB needed)

How It Works:

  • Store interfaces defined in org.finos.calm.store
  • Implementations in store/mongo/ and store/nitrite/
  • Producers in store/producer/ select implementation at runtime

Example Producer Pattern:

@ApplicationScoped
public class ArchitectureStoreProducer {
    
    @Inject
    @ConfigProperty(name = "calm.database.mode", defaultValue = "mongo")
    String databaseMode;
    
    @Inject MongoArchitectureStore mongoStore;
    
    @Inject NitriteArchitectureStore nitriteStore;
    
    @Produces
    @ApplicationScoped
    public ArchitectureStore produceStore() {
        return "standalone".equals(databaseMode) 
            ? nitriteStore 
            : mongoStore;
    }
}

Security Profiles

Default Profile (no auth):

  • All endpoints open
  • Good for development

Secure Profile (Keycloak):

  • OAuth2/OIDC authentication
  • Requires Keycloak running on https://localhost:9443
  • Self-signed certificates for local dev

Key Concepts

Quarkus Dev Mode

Adding New Storage Modes

  1. Create implementation package: org.finos.calm.store.newmode
  2. Implement store interfaces
  3. Update Producer classes to inject and conditionally return new implementation
  4. Add mode to configuration documentation

Integration Tests

  • Located in src/integration-test/java/
  • Use TestContainers (requires Docker)
  • Run via Maven only: ../mvnw -P integration verify
  • Cannot run from IDE unless Docker configured

API Documentation

  • OpenAPI spec auto-generated by Quarkus
  • Available at /q/swagger-ui in dev/secure mode
  • Annotations: @Operation, @APIResponse, etc.

Testing

Unit Tests

../mvnw test                  # All unit tests
../mvnw test -Dtest=ClassName # Specific test class

Integration Tests

../mvnw -P integration verify  # Requires Docker running

Test Structure

  • src/test/java/ - Unit tests (fast, no containers)
  • src/integration-test/java/ - Integration tests (TestContainers)

Common Tasks

Adding a New REST Endpoint

  1. Create resource class in resources/
  2. Implement service logic in services/
  3. Add store methods if needed in store/
  4. Write unit tests in test/
  5. Add integration test in integration-test/
  6. Document with OpenAPI annotations

Adding a New Storage Backend

  1. Create package: org.finos.calm.store.mybackend
  2. Implement all store interfaces
  3. Update all Producer classes to include new implementation
  4. Add conditional logic based on calm.database.mode
  5. Document in README.md

Working with MongoDB

  1. Start dev MongoDB: cd local-dev && docker-compose up
  2. Connection details in application.properties
  3. Database name: calm-hub (default)

Secure Mode Development

  1. Generate certificates (see README.md)
  2. Start Keycloak: cd keycloak-dev && docker-compose up
  3. Login to Keycloak: https://localhost:9443 (admin/password)
  4. Switch to calm-hub-realm
  5. Use demo user for testing
  6. Run app: ../mvnw quarkus:dev -Dquarkus.profile=secure

Configuration Files

  • pom.xml - Maven dependencies and build config
  • src/main/resources/application.properties - Default config
  • src/main/resources/application-secure.properties - Secure profile config

Dependencies on Other Packages

calm-hub depends on:
  └── cli (via parent POM, but loosely coupled)

CALM Hub is largely independent - it's a standalone REST API server.

Common Pitfalls

  1. TestContainers Errors: Ensure Docker is running before integration tests
  2. Port Conflicts: Check if port 8080 is free (or change quarkus.http.port)
  3. MongoDB Connection: Start MongoDB before dev mode (unless using standalone)
  4. Certificate Issues: Use exact CN in URLs when using self-signed certs
  5. Profile Selection: Remember to pass -Dquarkus.profile=secure for secure mode

Known Issues

Java 24+ Thread-Local Access Warning

If using Java 24 or later, you may see thread-local access warnings during tests:

java.lang.IllegalAccessError: module java.base does not open java.lang to unnamed module

These warnings are harmless and don't affect test results. To suppress them, add JVM options:

../mvnw test -Dquarkus.args="--add-opens java.base/java.lang=ALL-UNNAMED"

Recommended: Use Java 21 LTS for development (as specified in pom.xml).

Quarkus-Specific Tips

Configuration

  • Use @ConfigProperty to inject config values
  • Profile-specific: %profile.property.name=value
  • Environment overrides: PROPERTY_NAME=value

CDI (Dependency Injection)

  • Use @Inject for dependency injection
  • Scopes: @ApplicationScoped, @RequestScoped
  • Producers: @Produces for factory methods

REST Endpoints

  • @Path for routing
  • @GET, @POST, @PUT, @DELETE for HTTP methods
  • @PathParam, @QueryParam for parameters

Useful Links