Movie Searcher

TL;DR

movie-searcher es una app full stack para buscar películas y consultar su detalle, con un backend que actúa como “proxy” para diferentes servicios de APIs de películas.

Lo importante del proyecto no es solo la UI: es cómo se combinan arquitectura hexagonal + backend reactivo + estado claro en Angular para que la app sea mantenible.

Qué quería resolver de verdad

La necesidad no era únicamente “mostrar resultados”. Quería resolver tres problemas reales:

1. Evitar que el frontend hablara directamente con OMDb/TMDb o cualquier otro proovedor en el futuro.
2. Poder cambiar de proveedor sin reescribir el dominio.
3. Tener una experiencia de búsqueda fluida (carga, error, vacío, éxito) sin lógica caótica en UI.

A partir de ahí, la arquitectura salió casi sola.

Arquitectura hexagonal, pero aplicada (no solo dibujada)

El backend separa el caso de uso de los detalles externos:

• Puerto de entrada: QueryMovieUseCase
• Servicio de aplicación: SearchMovieService
• Puerto de salida: MovieCatalog
• Adaptadores externos: OmdbMovieCatalogAdapter y TmdbMovieCatalogAdapter

La ventaja práctica: el dominio no sabe si los datos vienen de OMDb o TMDb.

Además, el cambio de proveedor se hace por configuración (movies.provider), apoyado por @ConditionalOnProperty.

Cómo se ve eso en el flujo real

Cuando el usuario busca “interstellar”:

1. Angular actualiza la URL (?search=interstellar&page=1).
2. El componente reacciona al cambio de query params.
3. Llama al backend (/api/v1/movies).
4. El controller delega en el caso de uso.
5. El caso de uso usa el puerto MovieCatalog.
6. Se inyecta el adaptador OMDb o TMDb según configuración.
7. Se transforma a modelo de dominio y luego a DTO de salida.
8. Se devuelven cabeceras de caché + respuesta final.

Este recorrido mantiene responsabilidades muy claras en ambos lados.

Backend: ejemplo real del controller reactivo

Fragmento real de 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
}

Lo interesante aquí:

• El controller es fino: delega negocio en useCase.
• Se mantiene un flujo reactivo claro con Mono.
• Se define política de caché HTTP explícita (Cache-Control, Vary).
• defaultIfEmpty evita nulls y deja un 404 limpio.

Detalle de película

También añadí un manejador global para que los errores salgan con un formato consistente (ProblemDetail) y con códigos HTTP correctos.

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
}

Qué aporta este enfoque:

• Evita respuestas de error incoherentes entre endpoints.
• Mapea casos esperables a códigos concretos (400, 404, 405, 401).
• Deja un fallback para errores no controlados (500) sin romper el contrato de API.

Frontend Angular: estado de búsqueda bien modelado

Fragmento real de 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
  });

Por qué esta parte me gusta:

• El estado de pantalla está modelado como unión (idle/loading/error/loaded).
• La URL es fuente de verdad para búsqueda y paginación.
• debounceTime evita llamadas innecesarias al teclear.
• shareReplay evita duplicar peticiones cuando hay múltiples consumidores.

Búsqueda de películas

Decisiones técnicas que marcaron diferencia

• Hexagonal de verdad: puertos y adaptadores, no acoplar dominio al proveedor.
• Seguridad pragmática: JWT en cookie HttpOnly para no exponer token en JS.
• Caché en dos niveles: Caffeine en servidor + cabeceras HTTP al cliente.
• UI robusta: estados explícitos en Angular para evitar comportamientos ambiguos.
• Docker Compose: entorno reproducible para desarrollo y despliegue.

Límites actuales

Conclusión

Me dejó tres aprendizajes claros:

1. La arquitectura hexagonal sí aporta valor cuando necesitas integrar proveedores cambiantes.
2. La reactividad tiene sentido cuando tu cuello de botella es I/O externo.
3. En frontend, modelar bien el estado vale más que añadir componentes sin criterio.

Si hago una siguiente versión, priorizaría: usuarios reales, favoritos persistentes, filtros avanzados y métricas E2E de rendimiento.