Movie Searcher

TL;DR

movie-searcher is a full-stack app for searching movies and viewing details, with a backend that acts as a “proxy” for different movie API providers.

What matters in this project is not only the UI: it is how hexagonal architecture + reactive backend + clear Angular state combine to keep the app maintainable.

What I actually wanted to solve

The need was not just “show results.” I wanted to solve three real problems:

1. Avoid having the frontend talk directly to OMDb/TMDb or any future provider.
2. Be able to switch providers without rewriting the domain.
3. Keep search UX smooth (loading, error, empty, success) without chaotic UI logic.

From there, the architecture came almost naturally.

Hexagonal architecture, but applied (not just diagrammed)

The backend separates use-case logic from external details:

• Input port: QueryMovieUseCase
• Application service: SearchMovieService
• Output port: MovieCatalog
• External adapters: OmdbMovieCatalogAdapter and TmdbMovieCatalogAdapter

Practical benefit: the domain does not know whether data comes from OMDb or TMDb.

Also, provider switching is configuration-based (movies.provider), powered by @ConditionalOnProperty.

How this looks in the real flow

When a user searches for “interstellar”:

1. Angular updates the URL (?search=interstellar&page=1).
2. The component reacts to query param changes.
3. It calls the backend (/api/v1/movies).
4. The controller delegates to the use case.
5. The use case calls the MovieCatalog port.
6. OMDb or TMDb adapter is injected by configuration.
7. Data is transformed into domain model and then output DTO.
8. Cache headers + final response are returned.

This path keeps responsibilities very clear on both sides.

Backend: real reactive controller example

Real snippet from MovieController:

29
@Override
30
@GetMapping(produces = MediaType.APPLICATION_JSON_VALUE)
31
public Mono<ResponseEntity<MoviePageResponse>> searchByTitle(String query, int page) {
32
    return useCase.searchByTitle(query, page)
33
            .map(this::toResponse)
34
            .map(response -> ResponseEntity.ok()
35
                    .cacheControl(CacheControl.maxAge(60, TimeUnit.MINUTES)
36
                            .cachePrivate()
37
                            .mustRevalidate()
38
                    )
39
                    .header("Vary", "Cookie")
40
                    .body(response));
41
}
42

43
@Override
44
@GetMapping(value = "/{imdbId}", produces = MediaType.APPLICATION_JSON_VALUE)
45
public Mono<ResponseEntity<MovieDetailResponse>> findByImdbId(@PathVariable String imdbId) {
46
    return useCase.findByImdbId(imdbId)
47
            .map(mapper::toDetail)
48
            .map(movie -> ResponseEntity.ok()
49
                    .cacheControl(CacheControl.maxAge(60, TimeUnit.MINUTES)
50
                            .cachePrivate()
51
                            .cachePublic()
52
                    )
53
                    .header("Vary", "Cookie")
54
                    .body(movie))
55
            .defaultIfEmpty(ResponseEntity.notFound().build());
56
}

What is interesting here:

• The controller is thin: business logic is delegated to useCase.
• Reactive flow stays clear with Mono.
• HTTP cache policy is explicit (Cache-Control, Vary).
• defaultIfEmpty avoids nulls and provides a clean 404.

Movie detail

I also added a global handler so errors return with consistent format (ProblemDetail) and correct HTTP status codes.

13
@ExceptionHandler(ConstraintViolationException.class)
14
public ProblemDetail handleConstraintViolation(ConstraintViolationException ex) {
15
    return ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, ex.getMessage());
16
}
17

18
@ExceptionHandler(MovieNotFoundException.class)
19
public ProblemDetail handleMovieNotFound(MovieNotFoundException ex) {
20
    return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
21
}
22

23
@ExceptionHandler(MethodNotAllowedException.class)
24
public ProblemDetail handleMethodNotAllowed(MethodNotAllowedException ex) {
25
    return  ProblemDetail.forStatusAndDetail(HttpStatus.METHOD_NOT_ALLOWED, ex.getMessage());
26
}
27

28
@ExceptionHandler(AuthenticationException.class)
29
public ProblemDetail handleAuthError(AuthenticationException ex) {
30
    return ProblemDetail.forStatusAndDetail(HttpStatus.UNAUTHORIZED, ex.getMessage());
31
}
32

33
@ExceptionHandler(Exception.class)
34
public ProblemDetail handleGenericError(Exception ex) {
35
    return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR, ex.getMessage());
36
}

What this approach adds:

• Prevents inconsistent error responses across endpoints.
• Maps expected cases to specific statuses (400, 404, 405, 401).
• Provides a fallback for unhandled errors (500) without breaking API contract.

Angular frontend: properly modeled search state

Real snippet from movie-list-page.component.ts:

52
moviesPageState$ = this.route.queryParamMap.pipe(
53
  map((params) => ({
54
    query: (params.get("search") ?? "").trim(),
55
    page: +(params.get("page") ?? 1),
56
  })),
57
  distinctUntilChanged((a, b) => a.query === b.query && a.page === b.page),
58
  switchMap(({ query, page }) => {
59
    if (!query) {
60
      return of<PageState>({ state: "idle" });
61
    }
62

63
    return this.movies.searchMovies(query, page).pipe(
64
      map((page) => ({ state: "loaded", page }) as const),
65
      startWith({ state: "loading" } as const),
66
      catchError((error) => of({ state: "error", error } as const)),
67
    );
68
  }),
69
  shareReplay({ bufferSize: 1, refCount: true }),
70
);
71

72
this.searchControl.valueChanges
73
  .pipe(debounceTime(250), distinctUntilChanged())
74
  .subscribe((value) => {
75
    const trimmed = value?.trim();
76
    const queryParams = trimmed
77
      ? { search: trimmed, page: 1 }
78
      : { search: null, page: null };
79

80
    void this.router.navigate([], {
81
      relativeTo: this.route,
82
      queryParams,
83
      queryParamsHandling: "merge",
84
    });
85
  });

Why I like this part:

• Screen state is modeled as a union (idle/loading/error/loaded).
• URL is the source of truth for search and pagination.
• debounceTime avoids unnecessary calls while typing.
• shareReplay prevents duplicate requests with multiple subscribers.

Movie search list

Technical decisions that made a difference

• Real hexagonal architecture: ports/adapters, domain not coupled to provider.
• Pragmatic security: JWT in an HttpOnly cookie so token is not exposed to JS.
• Two-level cache: Caffeine server-side + HTTP headers client-side.
• Robust UI: explicit Angular states to avoid ambiguous behavior.
• Docker Compose: reproducible environment for development and deployment.

Current limits

Conclusion

It left me with three clear takeaways:

1. Hexagonal architecture does add value when you need to integrate changing providers.
2. Reactivity makes sense when your bottleneck is external I/O.
3. In frontend, modeling state well matters more than adding components without criteria.

If I build a next version, I would prioritize: real users, persistent favorites, advanced filters, and end-to-end performance metrics.