🌌 Interdimensional Service

interdimensional-service is a Spring Boot microservice that wraps the Rick and Morty API using Hexagonal Architecture and CQRS (Query side).

The service goes beyond a simple proxy:

• It introduces MongoDB-based read cache for Characters, Episodes and Locations.
• External API calls are only made on cache miss.
• Retrieved data is persisted in MongoDB for future queries.

If it looks overengineered for Rick & Morty…
Yes. That is entirely intentional.

---

🧱 Architecture Overview

The project follows Hexagonal Architecture (Ports & Adapters) + CQRS (Query side).

🟡 Domain Layer

Pure business models, framework-agnostic.

• Character
• Episode
• Location

No Spring, no persistence annotations.

---

🔵 Application Layer

Contains use cases and orchestration logic.

Inbound ports (what the app offers)

• CharacterQueryPort
• EpisodeQueryPort
• LocationQueryPort
• GetHealthQueryPort

Outbound ports (what the app needs)

• External API access:
  • LoadCharacterPort
  • LoadEpisodePort
  • LoadLocationPort
• Mongo cache access:
  • LoadCharacterCachePort
  • LoadEpisodeCachePort
  • LoadLocationCachePort

Application services

• CharacterQueryService
• EpisodeQueryService
• LocationQueryService
• GetHealthQueryService

Responsibilities:

• Validate inputs
• Normalize pagination
• Query Mongo cache first
• Fallback to external API
• Persist results in Mongo
• Throw explicit domain-level exceptions

Exceptions

• CharacterNotFoundException
• EpisodeNotFoundException
• LocationNotFoundException

---

🟣 Infrastructure Layer

All technical details live here.

Inbound adapters (REST)

• Controllers:
  • CharacterController
  • EpisodeController
  • LocationController
  • HealthController
• DTOs:
  • CharacterResponseDto
  • EpisodeResponseDto
  • LocationResponseDto
• Error handling:
  • RestExceptionHandler
  • ErrorResponse

Outbound adapters

HTTP (external API)

• CharacterApiAdapter
• EpisodeApiAdapter
• LocationApiAdapter

Uses WebClient to consume the Rick & Morty API.

MongoDB (read cache)

• Documents:
  • CharacterDocument
  • EpisodeDocument
  • LocationDocument
• Repositories:
  • CharacterMongoRepository
  • EpisodeMongoRepository
  • LocationMongoRepository
• Adapters:
  • CharacterMongoAdapter
  • EpisodeMongoAdapter
  • LocationMongoAdapter

Mongo acts as a read-through cache:

1. Query Mongo
2. If not found → query external API
3. Persist result in Mongo
4. Return domain model

---

📁 Project Structure

├───main
│   ├───java
│   │   └───com
│   │       └───interdimensional
│   │           │   InterdimensionalServiceApplication.java
│   │           │
│   │           ├───application
│   │           │   ├───command
│   │           │   └───query
│   │           │       ├───exception
│   │           │       │       CharacterNotFoundException.java
│   │           │       │       EpisodeNotFoundException.java
│   │           │       │       LocationNotFoundException.java
│   │           │       │
│   │           │       ├───ports
│   │           │       │   ├───character
│   │           │       │   │       CharacterQueryPort.java
│   │           │       │   │       LoadCharacterCachePort.java
│   │           │       │   │       LoadCharacterPort.java
│   │           │       │   │
│   │           │       │   ├───episode
│   │           │       │   │       EpisodeQueryPort.java
│   │           │       │   │       LoadEpisodeCachePort.java
│   │           │       │   │       LoadEpisodePort.java
│   │           │       │   │
│   │           │       │   ├───health
│   │           │       │   │       GetHealthQueryPort.java
│   │           │       │   │
│   │           │       │   └───location
│   │           │       │           LoadLocationCachePort.java
│   │           │       │           LoadLocationPort.java
│   │           │       │           LocationQueryPort.java
│   │           │       │
│   │           │       └───service
│   │           │               CharacterQueryService.java
│   │           │               EpisodeQueryService.java
│   │           │               GetHealthQueryService.java
│   │           │               LocationQueryService.java
│   │           │
│   │           ├───domain
│   │           │   ├───character
│   │           │   │       Character.java
│   │           │   │
│   │           │   ├───episode
│   │           │   │       Episode.java
│   │           │   │
│   │           │   └───location
│   │           │           Location.java
│   │           │
│   │           └───infrastructure
│   │               ├───adapters
│   │               │   ├───in
│   │               │   │   └───rest
│   │               │   │       │   HealthController.java
│   │               │   │       │
│   │               │   │       ├───character
│   │               │   │       │       CharacterController.java
│   │               │   │       │       CharacterResponseDto.java
│   │               │   │       │
│   │               │   │       ├───episode
│   │               │   │       │       EpisodeController.java
│   │               │   │       │       EpisodeResponseDto.java
│   │               │   │       │
│   │               │   │       ├───error
│   │               │   │       │       ErrorResponse.java
│   │               │   │       │       RestExceptionHandler.java
│   │               │   │       │
│   │               │   │       └───location
│   │               │   │               LocationController.java
│   │               │   │               LocationResponseDto.java
│   │               │   │
│   │               │   └───out
│   │               │       ├───events
│   │               │       ├───http
│   │               │       │   ├───character
│   │               │       │   │       CharacterApiAdapter.java
│   │               │       │   │       CharacterPageResponse.java
│   │               │       │   │       CharacterResponse.java
│   │               │       │   │
│   │               │       │   ├───episode
│   │               │       │   │       EpisodeApiAdapter.java
│   │               │       │   │       EpisodePageResponse.java
│   │               │       │   │       EpisodeResponse.java
│   │               │       │   │
│   │               │       │   └───location
│   │               │       │           LocationApiAdapter.java
│   │               │       │           LocationPageResponse.java
│   │               │       │           LocationResponse.java
│   │               │       │
│   │               │       ├───jpa
│   │               │       └───mongo
│   │               │           ├───character
│   │               │           │       CharacterDocument.java
│   │               │           │       CharacterMongoAdapter.java
│   │               │           │       CharacterMongoRepository.java
│   │               │           │
│   │               │           ├───episode
│   │               │           │       EpisodeDocument.java
│   │               │           │       EpisodeMongoAdapter.java
│   │               │           │       EpisodeMongoRepository.java
│   │               │           │
│   │               │           └───location
│   │               │                   LocationDocument.java
│   │               │                   LocationMongoAdapter.java
│   │               │                   LocationMongoRepository.java
│   │               │
│   │               └───configuration
│   │                       CorsProperties.java
│   │                       GlobalCorsConfig.java
│   │                       OpenApiConfig.java
│   │                       WebClientConfig.java
│   │
│   └───resources
│           application-dev.yml
│           application-prod.yml
│           application.yml
│
└───test
    └───java
        └───com
            └───interdimensional
                ├───application
                │   └───query
                │       └───service
                │               CharacterQueryServiceTest.java
                │               EpisodeQueryServiceTest.java
                │               LocationQueryServiceTest.java
                │
                ├───infrastructure
                │   └───adapters
                │       ├───in
                │       │   └───rest
                │       │       │   HealthControllerTest.java
                │       │       │
                │       │       ├───character
                │       │       │       CharacterControllerTest.java
                │       │       │
                │       │       ├───episode
                │       │       │       EpisodeControllerTest.java
                │       │       │
                │       │       └───location
                │       │               LocationControllerTest.java
                │       │
                │       └───out
                │           ├───character
                │           │       CharacterApiAdapterTest.java
                │           │
                │           ├───episode
                │           │       EpisodeApiAdapterTest.java
                │           │
                │           └───location
                │                   LocationApiAdapterTest.java
                │
                └───integration
                        CharacterIntegrationTest.java
                        EpisodeIntegrationTest.java
                        LocationIntegrationTest.java

---

📡 Exposed Endpoints

Characters

• GET /api/v1/characters/{id}
• GET /api/v1/characters?page=1&name=Rick&status=alive

Episodes

• GET /api/v1/episodes/{id}
• GET /api/v1/episodes?page=1&name=Pilot

Locations

• GET /api/v1/locations/{id}
• GET /api/v1/locations?page=1&name=Earth

Health

• GET /health

---

🧪 Testing Strategy

• Unit tests: Focus on application services and domain logic.
• Controller slice tests: Use MockMvc to verify HTTP contracts.
• Adapter tests: Verify correct mapping and error handling.
• Integration tests (End-to-End): - Full context load (@SpringBootTest).
  • MockWebServer running on fixed ports to simulate the external API.
  • MongoDB (Testcontainers or Embedded) with explicit database cleanup between tests to ensure cache consistency.

---

🧰 Tech Stack

Component	Version
Java	21
Spring Boot	3.3.x
Spring Web MVC	REST
Spring WebFlux	WebClient
Spring Data MongoDB	Cache
JUnit 5	Testing
MockWebServer	External API
Lombok	Boilerplate
OpenAPI	Swagger UI

---

🚀 Run the Service

mvn clean verify
mvn spring-boot:run

• Swagger: http://localhost:8080/swagger-ui/index.html
• Health: /health

---

🔮 Roadmap

• Command side (CQRS)
• Write persistence (JPA)
• Observability
• Metrics & tracing

---

📄 License

MIT — free to use across dimensions.