Claprec: Frontend - Angular, NgRx, and OpenAPI (3/6)

Series Roadmap

• Product Overview (1/6)
• Architecture: N-Tier Design, Decoupling, and Microservices (2/6)
• Frontend: Angular, NgRx, and OpenAPI Integration (3/6)
• Machine Learning in Practice (4/6)
• Database Design and Data Modeling (5/6)
• Engineering Tradeoffs: Limited Time vs. Ideal Architecture (6/6)

---

Opinionated Structure and DX

Transitioning from a strong background in Next.js and Vue to Angular offered a unique opportunity to contrast distinct architectural philosophies. While Next.js provides an unparalleled Developer Experience (DX) for Server-Side Rendering (SSR), Angular's opinionated structure proves invaluable for enterprise-scale SPAs, preventing the architectural sprawl often seen in less rigid frameworks.

In this third installment of the Claprec series, I dive into the frontend implementation, focusing on the most challenging aspects: managing complex reactive state, handling intricate UI interactions like real-time chat scrolling, and enforcing type safety via Contract-First Design.

---

Advanced Scroll Management in Real-Time Chat

One of the most significant UX challenges was implementing a real-time chat interface. Default browser rendering behavior during DOM updates can cause unintended scroll shifts: when chat history is loaded, the scroll position is not preserved and snaps to the top, while incoming messages do not trigger automatic scroll to the bottom. To solve this, scroll behavior must be explicitly controlled - preserving the current position during chat history loads, and conditionally snapping to the bottom only when the user is already at the bottom when new messages arrive.

To solve this, I had to deeply leverage Angular's lifecycle hooks and RxJS streams to calculate scroll offsets relative to content height changes.

Key implementation details

• Lifecycle Hook: Used ngAfterViewInit to dispatch header/footer dimensions to the store, ensuring the chat container height was calculated correctly before rendering.
• Scroll Restoration: Implemented logic to maintain scroll position when prepending history (infinite scroll upwards) vs. snapping to bottom for new messages.

// app.component.ts

public ngAfterViewInit(): void {
  this._store.dispatch(
    setHeaderHeightAction({
      height: this._header.nativeElement.offsetHeight,
    }),
  );

  this._store.dispatch(
    setFooterHeightAction({
      height: this._footer.nativeElement.offsetHeight,
    }),
  );
}

// chat-page.component.ts

protected setChatsAndScroll(chats: DtoPlainChat[], chatType: "INITIAL" | "OLD" | "NEW"): void {
  const oldScrollTop = this._chatSection.nativeElement.scrollTop;
  const oldHeight = this._chatSection.nativeElement.scrollHeight;
  const wasUnscrollable = this._chatSection.nativeElement.scrollHeight
    === this._chatSection.nativeElement.clientHeight;

  this.chats$.next(chats);

  timer(1).subscribe(() => {
    const scrollToBottom = (): void => {
      this._chatSection.nativeElement.scrollTop
        = this._chatSection.nativeElement.scrollHeight
          - this._chatSection.nativeElement.clientHeight;
    };

    const isUnscrollable = this._chatSection.nativeElement.scrollHeight
      === this._chatSection.nativeElement.clientHeight;

    if (chatType === "INITIAL" && isUnscrollable) {
      this.sendChatLoadRequestForMoreChats("INITIAL");

      return;
    }

    if (
      (wasUnscrollable && !isUnscrollable)
      || chatType === "INITIAL"
      || this._scrollState$.getValue() === "BOTTOM"
    ) {
      scrollToBottom();

      return;
    }

    const newHeight = this._chatSection.nativeElement.scrollHeight;
    const newTopScroll = newHeight - oldHeight;

    if (this._scrollState$.getValue() === "MIDDLE") {
      this._chatSection.nativeElement.scrollTop = oldScrollTop;
    }

    if (this._scrollState$.getValue() === "TOP") {
      this._chatSection.nativeElement.scrollTop
      = chatType === "OLD" ? newTopScroll : oldScrollTop;
    }
  });
}

Additionally, handling responsive layouts proved tricky with the window API. Standard window.innerHeight often fails when mobile browser toolbars appear or when using DevTools mobile viewport simulation. I utilized window.visualViewport for accurate height calculations.

// chat-page.component.ts

this._windowHeight$.next(
  window.visualViewport?.height ?? window.innerHeight,
);

---

Architecting Reusable Pagination & History Management

Pagination is often implemented ad-hoc, leading to boilerplate in every component. To avoid this, I engineered a generic PaginationHelper class. This class encapsulates the complexity of fetching, storing, and synchronizing pagination state with the URL query parameters.

The Challenge

Supporting multiple independent paginators on a single page without state collision.

The Solution

I implemented a PaginationHistory class that maps query parameters to specific paginated responses, ensuring that everything is cached per page. The helper exposes a isPaused setter, allowing specific paginators to ignore URL updates while another paginator is active. This abstraction handles "clean start", context switching, and auto-correction of page numbers.

// paginator.helper.ts

interface IPagination {
  parsedPageNumber: number;
  apiQueryParams: IQueryParam[] | null;
}

interface IPaginationContext<T> {
  items: T[];
  pageNumber: number;
  totalPages: number;
}

class PaginationHistory<T> {
  private _historyMap = new Map<string, IPaginatedResponse<T>[] | null>();

  private getPaginatedResponsesFromHistoryMap(
    apiQueryParams: IQueryParam[] | null,
  ): IPaginatedResponse<T>[] | null | undefined {
    return this._historyMap.get(JSON.stringify(apiQueryParams));
  }

  public getPaginatedResponse(
    pagination: IPagination,
  ): IPaginatedResponse<T> | undefined {
    return this.getPaginatedResponsesFromHistoryMap(
      pagination.apiQueryParams,
    )?.find(
      paginatedResponses =>
        paginatedResponses.metadata?.pageNumber === pagination.parsedPageNumber,
    );
  }

  public setOrAppendPaginatedResponseToHistoryMap(
    apiQueryParams: IQueryParam[] | null,
    paginatedResponse: IPaginatedResponse<T> | null,
  ): void {
    if (!paginatedResponse) {
      this._historyMap.set(
        JSON.stringify(apiQueryParams),
        paginatedResponse,
      );

      return;
    }

    const paginatedResponsesFromHistoryMap
      = this.getPaginatedResponsesFromHistoryMap(apiQueryParams);

    this._historyMap.set(
      JSON.stringify(apiQueryParams),
      paginatedResponsesFromHistoryMap
        ? [
          ...paginatedResponsesFromHistoryMap,
          paginatedResponse,
        ]
        : [paginatedResponse],
    );
  }

  public clearHistoryMap(): void {
    this._historyMap = new Map<string, IPaginatedResponse<T>[]>();
  }
}

export class PaginationHelper<T> {
  private readonly _subscriptionToPagination$
    = new BehaviorSubject<Subscription | null | undefined>(undefined);

  private readonly _isFetching$ = new BehaviorSubject(false);
  private readonly _isClearStateLoading$ = new BehaviorSubject(false);
  private readonly _isCleanStartLoading$ = new BehaviorSubject(false);
  private readonly _isClearContextLoading$ = new BehaviorSubject(false);
  private readonly _isChangeContextLoading$ = new BehaviorSubject(false);

  public readonly isLoading$ = combineLatest([
    this._subscriptionToPagination$,
    this._isFetching$,
    this._isChangeContextLoading$,
    this._isClearContextLoading$,
    this._isClearStateLoading$,
    this._isCleanStartLoading$,
  ]).pipe(
    map(
      ([
        subscriptionToPagination,
        isFetching,
        isChangingContextLoading,
        isClearContextLoading,
        isClearStateLoading,
        isCleanStartLoading,
      ]) => subscriptionToPagination === null
        || subscriptionToPagination === undefined
        || isFetching
        || isChangingContextLoading
        || isClearContextLoading
        || isClearStateLoading
        || isCleanStartLoading,
    ),
  );

  private readonly _isPaused$ = new BehaviorSubject<boolean>(false);

  public set isPaused(isPaused: boolean) {
    this._isPaused$.next(isPaused);
  }

  private readonly _apiQueryParams$
    = new ReplaySubject<IQueryParam[] | null>(1);

  public set apiQueryParams(newApiQueryParams: IQueryParam[] | null) {
    this._apiQueryParams$.next(newApiQueryParams);
  }

  private _paginationContext: IPaginationContext<T> | null | undefined;

  public get paginationContext(): IPaginationContext<T> | null | undefined {
    return this._paginationContext;
  }

  private _pagination: Observable<IPagination>;
  private readonly _paginationHistory = new PaginationHistory<T>();

  constructor(
    private _apiUrl: string,
    public pageSize: number,
    private _router: Router,
    private _snackBar: MatSnackBar,
    private _route: ActivatedRoute,
    private _httpClient: HttpClient,
    private _apiService: ApiService,
  ) {
    this._pagination
      = combineLatest([
        this._route.queryParamMap,
        this._apiQueryParams$,
        this._isPaused$,
      ]).pipe(
        filter(([, , isPaused]) => !isPaused),
        map(([queryParamMap, apiQueryParams]): IPagination => ({
          apiQueryParams,
          parsedPageNumber: parsePageNumberFromQueryParam(
            queryParamMap.get(QUERY_PARAMETERS.PAGE_NUMBER),
          ),
        })),
        distinctUntilChanged(
          (prev, curr) =>
            prev.parsedPageNumber === curr.parsedPageNumber
            && JSON.stringify(prev.apiQueryParams)
            === JSON.stringify(curr.apiQueryParams),
        ),
        startWith(null),
        pairwise(),
        tap(([prev, curr]) => {
          if (!prev) {
            this.handlePagination(curr!);

            return;
          }

          if (
            curr!.parsedPageNumber !== 1
            && JSON.stringify(prev.apiQueryParams)
            !== JSON.stringify(curr!.apiQueryParams)
          ) {
            updateRoutePageNumber(1, _router, _route);

            return;
          }

          this.handlePagination(curr!);
        }),
        map(([, curr]) => curr!),
      );
  }

  public cleanStart(): void {
    this._isCleanStartLoading$.next(true);
    this.clearState();
    this.resetPaginationSubscription();
    this._isCleanStartLoading$.next(false);
  }

  public async handlePageEvent(
    e: PageEvent,
    target: HTMLElement,
  ): Promise<void> {
    const pageNumber = e.pageIndex + 1;

    await updateRoutePageNumber(pageNumber, this._router, this._route);

    target.scrollIntoView({
      behavior: "smooth",
      block: "start",
    });
  }

  private handlePagination(
    pagination: IPagination,
  ): void {
    const paginatedResponse
      = this._paginationHistory.getPaginatedResponse(pagination);

    if (paginatedResponse) {
      this._isFetching$
        .pipe(
          filter(isFetching => !isFetching),
          take(1),
        )
        .subscribe(() => {
          this.changeContext(paginatedResponse);
        });

      return;
    }

    this.fetchNewPaginatedResponse(pagination);
  }

  private fetchNewPaginatedResponse(
    pagination: IPagination,
  ): void {
    this._isFetching$.next(true);

    let params = chainHttpParams([
      API_PAGINATION_QUERY_PARAMS_CALLBACKS.PAGE_SIZE(this.pageSize),
      API_PAGINATION_QUERY_PARAMS_CALLBACKS.PAGE_NUMBER(
        pagination.parsedPageNumber,
      ),
    ]);

    if (pagination.apiQueryParams) {
      params = chainHttpParams(pagination.apiQueryParams, params);
    }

    this._httpClient
      .get<IPaginatedResponse<T>>(
        `${this._apiService.getApiV1Url()}/${this._apiUrl}`,
        {
          params,
          observe: "response",
        },
      )
      .subscribe({
        next: response => {
          if (response.status === HTTP_STATUS_CODE.NO_CONTENT) {
            this._paginationHistory.setOrAppendPaginatedResponseToHistoryMap(
              pagination.apiQueryParams,
              null,
            );

            this.clearContext();

            return;
          }

          const newPaginatedResponse = response.body!;

          const fetchedPageNumber = newPaginatedResponse.metadata!.pageNumber!;

          if (pagination.parsedPageNumber !== fetchedPageNumber) {
            this._paginationHistory.setOrAppendPaginatedResponseToHistoryMap(
              pagination.apiQueryParams,
              newPaginatedResponse,
            );

            updateRoutePageNumber(fetchedPageNumber, this._router, this._route);

            return;
          }

          this._paginationHistory.setOrAppendPaginatedResponseToHistoryMap(
            pagination.apiQueryParams,
            newPaginatedResponse,
          );

          const paginatedResponse
            = this._paginationHistory.getPaginatedResponse(pagination);

          if (!paginatedResponse) {
            throw new Error("Logical error with insertion into map");
          }

          this.changeContext(paginatedResponse);
        },
        complete: () => this._isFetching$.next(false),
        error: httpError => {
          this._isFetching$.next(false);
          openSnackbarForUnexpectedError(this._snackBar, httpError);
        },
      });
  }

  private unsubcribeFromPagination(): void {
    if (!this._subscriptionToPagination$.getValue()) {
      return;
    }

    this._subscriptionToPagination$.getValue()!.unsubscribe();
    this._subscriptionToPagination$.next(null);
  }

  private resetPaginationSubscription(): void {
    this.unsubcribeFromPagination();

    this._subscriptionToPagination$.next(
      this._pagination.subscribe(),
    );
  }

  private clearState(): void {
    this._isClearStateLoading$.next(true);
    this.clearContext();
    this._paginationHistory.clearHistoryMap();
    this._isClearStateLoading$.next(false);
  }

  private clearContext(): void {
    this._isClearContextLoading$.next(true);
    this._paginationContext = null;
    this._isClearContextLoading$.next(false);
  }

  private changeContext(
    paginatedResponse: IPaginatedResponse<T>,
  ): void {
    this._isChangeContextLoading$.next(true);

    this.clearContext();

    this._paginationContext = {
      items: paginatedResponse.data!,
      pageNumber: paginatedResponse.metadata!.pageNumber!,
      totalPages: paginatedResponse.metadata!.totalRecords!,
    };

    this._isChangeContextLoading$.next(false);
  }
}

---

Recursive State Management with NgRx

Working with paginated recursive data, such as nested comments and replies, means dealing with a dynamic, unbalanced hierarchy where depth and width are unpredictable. Because this structure lacks the ordering or balancing constraints found in optimized trees, operations like search effectively degrade to linear complexity. To streamline the implementation, I flattened the state into an array within the NgRx store. This approach significantly reduces cognitive overhead and simplifies state management, though it introduces a reliance on linear scans to resolve entity relationships.

I defined a ICommentsWrapper interface to manage loading states (areCommentsLoading, areMoreCommentsLoading) and pagination metadata per entity, ensuring the UI remains responsive and data is retained efficiently.

// i-comments.state.ts

import { DtoCustomComment } from "../../../open_api";

export type CommentType =
  Omit<DtoCustomComment, "paginatedReplies"> & {
    isMediaLoading: boolean;
    isCommentLoading: boolean;
  };

export interface ICommentsWrapper {
  forId: string;
  lastPageNumber: number;
  areCommentsLoading: boolean;
  areMoreCommentsLoading: boolean;
  //
  hasMore?: boolean | null;
  comments?: CommentType[] | null;
}

export interface ICommentsState {
  commentsWrappers: ICommentsWrapper[] | null;
}

The Reactive Mindset Shift

Coming from Next.js/Vue, the shift to Angular required a fundamental change in mindset: Imperative -> Declarative.
While "Signals" are the new trend, RxJS Observables remain essential for modeling complex async streams in large systems. NgRx extends the Redux pattern by treating actions as streams, offering immense control over side effects, though with a steeper learning curve and higher boilerplate cost.

---

Contract-First Design & Type-Safe API Layer

Integrating a .NET backend with an Angular frontend usually risks DTO synchronization issues. I enforced a Contract-First Design using OpenAPI (Swagger).

Implementation

• Auto-Generation: DTOs are auto-generated from the backend spec, eliminating manual syncing.
• Type-Safe Endpoints: I constructed a centralized API configuration object. This ensures that changing a backend route requires minimal updates in the frontend codebase.

I extended this concept by creating objects that generate callbacks for path and query parameters, ensuring that every API call is strictly typed and validated at compile time.

// http-method.types.ts

export type HttpMethod =
  HTTP_METHOD.GET |
  HTTP_METHOD.PUT |
  HTTP_METHOD.POST |
  HTTP_METHOD.PATCH |
  HTTP_METHOD.DELETE;

export type CommonApiKeys = "GET" | "GET_MORE" | "CREATE" | "EDIT_PART" | "EDIT_WHOLE" | "LIST_PAGINATED" | "LIST_ALL" | "DELETE" | "DELETE_BULK";

// i-api-endpoint.ts

export interface IApiEndpoint<
  TRequestBody = any,
  TResponseBody = any,
  TQueryParams extends
  Record<
    string,
    (value: any) => IQueryParam
  > = Record<string, (value: any) => IQueryParam>,
> {
  path: string | ((...pathParameters: string[]) => string);
  method: HttpMethod;
  queryParams?: Record<"sorting", Record<string, (value: ENUM_SORTING) => IQueryParam[]>> | TQueryParams;
  roles?: Set<ENUM_ROLE>;
  flags?: Set<ENUM_API_FLAGS>;
  builders: IApiEndpointBuilders<TRequestBody, TResponseBody>;
}

export interface IApiEndpointBuilders<
  TRequestBody = any,
  TResponseBody = any,
> {
  createRequestBody: (body: TRequestBody) => TRequestBody;
  createResponseBody: (body: TResponseBody) => TResponseBody;
}

// api-url.helper.ts

export function createSortingQueryParamCallback(queryParam: string):
(value: ENUM_SORTING, order?: number) => IQueryParam[] {
  return function(value: ENUM_SORTING, order?: number): IQueryParam[] {
    return [
      {
        key: `Sorting.${queryParam}.SortingType`,
        value: value.toString(),
      },
      ...(
        order !== undefined
          ? [
            {
              key: `Sorting.${queryParam}.Order`,
              value: order,
            },
          ]
          : []
      ),
    ];
  };
}

export function createQueryParamCallBack<
  T extends string | number | boolean | string[] | number[] | boolean[],
>(queryParam: string): (value: T) => IQueryParam {
  return function(value: T): IQueryParam {
    return {
      key: queryParam,
      value: value,
    };
  };
}

export function chainHttpParams(
  queryParams: IQueryParam[],
  httpParams?: HttpParams,
): HttpParams {
  let actualHttpParams = httpParams ? httpParams : new HttpParams();

  for (const queryParam of queryParams) {
    if (Array.isArray(queryParam.value)) {
      actualHttpParams = actualHttpParams.appendAll({
        [queryParam.key]: queryParam.value,
      });
    }
    else {
      actualHttpParams = actualHttpParams.set(queryParam.key, queryParam.value);
    }
  }

  return actualHttpParams;
}

export function createApiEndpointBuilders<TRequestBody, TResponseBody>(
): IApiEndpointBuilders<TRequestBody, TResponseBody> {
  return {
    createRequestBody: (body: TRequestBody): TRequestBody => body,
    createResponseBody: (body: TResponseBody): TResponseBody => body,
  } satisfies IApiEndpointBuilders<TRequestBody, TResponseBody>;
}

export const withBuilders = <TRequestBody, TResponseBody>():
{
  builders: IApiEndpointBuilders<TRequestBody, TResponseBody>;
} => ({
  builders: createApiEndpointBuilders<TRequestBody, TResponseBody>(),
});

// api-urls.constants.ts

export const API_PAGINATION_QUERY_PARAMS_CALLBACKS = {
  PAGE_SIZE: createQueryParamCallBack<number>(
    API_PAGINATION_QUERY_PARAMS.PAGE_SIZE,
  ),
  PAGE_NUMBER: createQueryParamCallBack<number>(
    API_PAGINATION_QUERY_PARAMS.PAGE_NUMBER,
  ),
  INCLUDE_LINKS: createQueryParamCallBack<boolean>(
    API_PAGINATION_QUERY_PARAMS.INCLUDE_LINKS,
  ),
  INCLUDE_METADATA: createQueryParamCallBack<boolean>(
    API_PAGINATION_QUERY_PARAMS.INCLUDE_METADATA,
  ),
} as const;

export const API = {
  REVIEW: {
    GET: {
      method: HTTP_METHOD.GET,
      path: (reviewId: string) => `review/${reviewId}`,
      flags: new Set([ENUM_API_FLAGS.LOGGED_OPTIONAL]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, DtoRelatedReview>,

    GET_MORE: {
      method: HTTP_METHOD.GET,
      path: (reviewId: string) => `review/more/${reviewId}`,
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, DtoCalculatedReview>,

    CREATE: {
      path: "review",
      method: HTTP_METHOD.POST,
      flags: new Set([ENUM_API_FLAGS.LOGGED]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<InsertDtoReview, DtoPlainReview>,

    EDIT_WHOLE: {
      method: HTTP_METHOD.PUT,
      path: (reviewId: string) => `review/${reviewId}`,
      flags: new Set([
        ENUM_API_FLAGS.LOGGED, ENUM_API_FLAGS.BELONGS_TO_LOGGED_USER,
      ]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<UpdateDtoReview, DtoPlainReview>,

    LIST_PAGINATED: {
      method: HTTP_METHOD.GET,
      path: "review",
      queryParams: {
        PRODUCT_OR_BUSINESS_PARENT_IDS: createQueryParamCallBack<string[]>(
          API_QUERY_PARAMS.PRODUCT_OR_BUSINESS_PARENT_IDS,
        ),
        BUSINESS_ADDRESS_IDS: createQueryParamCallBack<string[]>(
          API_QUERY_PARAMS.BUSINESS_ADDRESS_IDS,
        ),
        RATINGS: createQueryParamCallBack<number[]>(API_QUERY_PARAMS.RATINGS),
        sorting: {
          RATING: createSortingQueryParamCallback(
            API_SORTING_QUERY_PARAMS.RATING,
          ),
          CREATED_AT: createSortingQueryParamCallback(
            API_SORTING_QUERY_PARAMS.CREATED_AT,
          ),
          VIEW_COUNT: createSortingQueryParamCallback(
            API_SORTING_QUERY_PARAMS.VIEW_COUNT,
          ),
        },
        ...API_PAGINATION_QUERY_PARAMS_CALLBACKS,
      },
      ...withBuilders(),
    } as const satisfies IApiEndpoint<
      undefined,
      DtoRelatedReviewPaginatedResponse
    >,

    DELETE: {
      method: HTTP_METHOD.DELETE,
      path: (reviewId: string) => `review/${reviewId}`,
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, undefined>,

    CREATE_MEDIA: {
      method: HTTP_METHOD.POST,
      path: (reviewId: string) => `review/${reviewId}/media`,
      flags: new Set([
        ENUM_API_FLAGS.LOGGED,
        ENUM_API_FLAGS.MULTIPART_FORM_DATA,
      ]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, DtoPlainMedia[]>,

    DELETE_MEDIA: {
      method: HTTP_METHOD.DELETE,
      path: (mediaId: string) => `review/media/${mediaId}`,
      flags: new Set([
        ENUM_API_FLAGS.LOGGED,
        ENUM_API_FLAGS.BELONGS_TO_LOGGED_USER,
      ]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, undefined>,

    CREATE_VIEW: {
      path: "review/view",
      method: HTTP_METHOD.POST,
      flags: new Set([ENUM_API_FLAGS.LOGGED_OPTIONAL]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<DtoCustomReviews, undefined>,

    RECOMMENDED: {
      method: HTTP_METHOD.GET,
      path: "review/recommended",
      flags: new Set([ENUM_API_FLAGS.LOGGED_OPTIONAL]),
      queryParams: {
        LAT: createQueryParamCallBack<number>(API_QUERY_PARAMS.LAT),
        LNG: createQueryParamCallBack<number>(API_QUERY_PARAMS.LNG),
        ...API_PAGINATION_QUERY_PARAMS_CALLBACKS,
      },
      ...withBuilders(),
    } as const satisfies IApiEndpoint<
      undefined,
      DtoRelatedReviewPaginatedResponse
    >,
  },
} as const satisfies
Record<string, Partial<Record<CommonApiKeys, IApiEndpoint>>> |
Record<string, Record<string, IApiEndpoint>>;

// write-review-for-product-page.component.ts

// usage (both request and response is strongly typed)

const postBody = {
  rating: this.rating,
  // ...
} as ExtractRequestType<typeof API.REVIEW.CREATE>;

this._httpClient
  .post<ExtractResponseType<typeof API.REVIEW.CREATE>>(
    `${this._apiService.getApiV1Url()}/${API.REVIEW.CREATE.path}`,
    postBody,
  )
  .subscribe({ 
    next: review => {
      // review.reviewId
      // ...
    }
  });

This high-setup-cost approach pays dividends in long-term maintainability and type safety.

---

Context-Aware Autocomplete Services

Standard autocomplete components are often isolated. However, in complex forms, one input often dictates the dataset of another (e.g., selecting a "City" filters the available "Zipcodes").

I built an autocomplete service architecture that accepts additionalParams via a BehaviorSubject. This allows the service to react to external changes, clear its current cache, and re-fetch data based on the new context. It handles debouncing, prefetching, and pagination internally.

// zipcode-autocomplete.service.ts

interface IAdditionalParams {
  cityId: number | null;
}

@Injectable({
  providedIn: "root",
})
export class ZipcodeAutocompleteService {
  public readonly additionalParams$ = new BehaviorSubject<IAdditionalParams>({
    cityId: null,
  });

  public readonly isLoading$ = new BehaviorSubject<boolean>(false);

  public readonly filteredData$ = new BehaviorSubject<DtoRelatedZipcode[]>([]);

  public readonly nextPageDebounced$ = new Subject<void>();

  public readonly citiesHasZipcodes$
    = new BehaviorSubject<ICityHasZipcodes>({});

  public preselected$ = new Subject<DtoRelatedZipcode>();

  private _prefetced$ = new BehaviorSubject<boolean>(false);

  private readonly _beforeFetchSearchSnapshots:
  IBeforeFetchSearchSnapshot<IAdditionalParams>[] = [];

  private readonly _afterFetchSearchSnapshots:
  IAfterFetchSearchSnapshot<DtoRelatedZipcode, IAdditionalParams>[] = [];

  private readonly _searchQuery$ = new Subject<string>();
  private readonly _fetchDebounce$ = new Subject<string>();

  constructor(
    private _httpClient: HttpClient,
    private _apiService: ApiService,
  ) { 
    // ...
  }

  public search(search: string): void {
    // ...
  }

  public prefetch(): void {
    // ... 
  }

  public preselect(preselectedZipcodeId?: string | null): void {
    // ...
  }

  private observeFetchDebounce(): void {
    // ...
  }

  private observeSearchQuery(): void {
    // ...
  }

  private observeNextPageDebounced(): void {
    // ...
  }

  private determineNextPageNumber(searchQuery: string): number {
    // ...
  }

  private checkIfAlreadyProceededToFetch(
    newBeforeFetchSearchSnapshot: IBeforeFetchSearchSnapshot<IAdditionalParams>,
  ): boolean {
    // ...
  }

  private filterDataBySearchQueryAndAdditionalParams(
    searchQuery: string,
  ): IAfterFetchSearchSnapshot<DtoRelatedZipcode, IAdditionalParams>[] {
    // ...
  }

  private filterData(searchQuery: string): void {
    // ...
  }

  private fetchData(
    searchSnapshotBeforeFetch: IBeforeFetchSearchSnapshot<IAdditionalParams>,
  ): void {
    // ...
  }
}

---

UI/UX Decisions & Layout Strategy

Angular Material Theming (M2/M3)

Implementing a robust Dark/Light theme toggle using Angular Material was surprisingly difficult. It required deep customization of the M2/M3 theming mixins to ensure contrast consistency across all components.

Intentional Layout Constraints

A deliberate UI decision was made to display content cards in a single column, leaving horizontal space unused.

The Rationale: The application tracks "dwell time" for Machine Learning analysis. Showing multiple entities simultaneously makes it impossible to determine which entity the user is actually viewing. The single-column constraint ensures high-fidelity data for the ML model, prioritizing backend accuracy over frontend real estate usage.

Modular Design

Every UI element, from cards to dialogs and the image cropper, is modular. This ensures consistency and reduces the cognitive load when maintaining the application.

---

Architectural Note: Client-Side Rendering Strategy

While the version of Angular used in Claprec is fully capable of SSR, I made a strategic decision to keep this application mostly Client-Side Rendered (CSR). This was a deliberate choice to optimize the development process for a demonstration environment:

1. No SEO Requirement: As the app is not a public marketing site, optimization for search engine crawlers was unnecessary.
2. Reduced Server Load: Eliminating server-side processing for HTML generation saved significant server resources.
3. Development Velocity: It simplified the architecture, allowing for faster iteration.

Transitioning the frontend to be SEO-friendly with SSR would be straightforward architecturally, but purposefully sticking to CSR saved time and reduced infrastructure complexity for this specific use case.

---

What's Next?

With a robust frontend architecture in place - specifically designed to capture high-fidelity user interaction data like dwell time - the stage is set for the intelligence layer of the application.

In the next part, Claprec: Machine Learning in Practice (4/6), the focus will shift from structural engineering to data science. I will discuss how the interaction data captured by the frontend is processed to train models, the specifics of the recommendation algorithms employed, and the challenges of integrating ML pipelines into a .NET environment.

Join me in the next post as we explore the engine that drives Claprec's predictive capabilities.

---

I'd love to hear your thoughts on these frontend architectural choices or answer any questions you might have in the comments below.