CLAUDE.md

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

Project Overview

LCC (Logistic Cost Calculator) is a Spring Boot 3.5.9 backend API for calculating complex logistics costs across supply chain networks. It handles materials, packaging, transportation rates, route planning, and multi-component cost calculations including customs duties, handling, inventory, and risk assessment.

Build & Run Commands

# Build the project
mvn clean install

# Run the application
mvn spring-boot:run

# Run all tests
mvn test

# Run a specific test class
mvn test -Dtest=NodeControllerIntegrationTest

# Run a specific test method
mvn test -Dtest=NodeControllerIntegrationTest#shouldReturnListOfNodesWithDefaultPagination

# Skip tests during build
mvn clean install -DskipTests

# Generate JAXB classes from WSDL (EU taxation service)
mvn jaxb:generate

Architecture

Layered Architecture

Controllers → DTOs → Services → Transformers → Repositories → MySQL

Package Structure (`de.avatic.lcc`)

controller/ - REST endpoints organized by domain (calculation, configuration, bulk, users, report)
service/access/ - Business logic for domain entities (PremisesService, MaterialService, NodeService, etc.)
service/calculation/ - Logistics cost calculation orchestration and step services
service/calculation/execution/steps/ - Individual calculation components (airfreight, handling, inventory, customs, etc.)
service/bulk/ - Excel-based bulk import/export operations
service/api/ - External API integrations (Azure Maps geocoding, EU taxation)
service/transformer/ - Entity-to-DTO mapping
repositories/ - JDBC-based data access (not JPA) with custom RowMappers
model/db/ - Database entity classes
dto/ - Data transfer objects for API contracts

Key Design Decisions

JDBC over JPA: Uses JdbcTemplate and NamedParameterJdbcTemplate for complex queries
Transformer layer: Explicit DTO mapping keeps entities separate from API contracts
Calculation chain: Cost calculations broken into fine-grained services in execution/steps/

Core Calculation Flow

CalculationExecutionService.launchJobCalculation()
  → ContainerCalculationService (container type selection: FEU/TEU/HC/TRUCK)
  → RouteSectionCostCalculationService (per-section costs)
  → AirfreightCalculationService
  → HandlingCostCalculationService
  → InventoryCostCalculationService
  → CustomCostCalculationService (tariff/duties)

Authorization Model

Role-based access control via @PreAuthorize annotations:

SUPER, CALCULATION, MATERIAL, FREIGHT, PACKAGING, BASIC

Testing

Integration tests use:

@SpringBootTest + @AutoConfigureMockMvc
@Transactional for test isolation
@Sql annotations for test data setup/cleanup from src/test/resources/master_data/
MySQL database (requires env.properties with DB_DATABASE, DB_USER, DB_PASSWORD)

Database

MySQL with Flyway migrations in src/main/resources/db/migration/
Migration naming: V{N}__{Description}.sql
Key tables: premiss, premiss_sink, premiss_route, calculation_job, node, material, packaging, container_rate, country_matrix_rate

External Integrations

Azure AD: OAuth2/OIDC authentication
Azure Maps: Geocoding and route distance calculations (GeoApiService, DistanceApiService)
EU Taxation API: TARIC nomenclature lookup for customs duties (EUTaxationApiService)

Configuration

Key properties in application.properties:

lcc.auth.identify.by - User identification method (workday)
calculation.job.processor.* - Async calculation job settings
Flyway enabled by default; migrations run on startup

3.7 KiB Raw Blame History