React 19와 TypeScript로 Web Console 다시 구성하기

Kubernetes Cluster Infra RCA Platform 개발 기록 8편

지난 글에서는 FastAPI 기반 Backend를 버리고 Spring Boot 3.5.15와 Java 21 기반 Platform으로 통합한 이유를 정리했습니다.

이번 글에서는 그 위에 Web Console을 다시 구성한 과정을 정리하려고 합니다.

초기 Web Console의 목표는 단순했습니다.

RCA report를 API JSON이 아니라 화면에서 볼 수 있게 만드는 것이었습니다.

하지만 프로젝트가 커지면서 Console도 더 명확한 역할이 필요해졌습니다.

Web Console은 예쁜 화면이 아니라, 장애 상황에서 운영자가 덜 헷갈리게 만드는 도구여야 한다.

그래서 React 19, TypeScript, Vite, Bootstrap 5 기반으로 Console 구조를 다시 잡았습니다.

왜 React와 TypeScript였나

RCA 플랫폼의 Web Console은 단순 페이지 몇 개로 끝나지 않습니다.

앞으로 보여줘야 할 정보가 많았습니다.

• cluster 목록
• Agent 상태
• evidence request
• RCA report
• incident timeline
• policy classification
• action request
• audit event
• export
• platform 설정

이런 데이터는 화면마다 구조가 다르고, API 응답도 계속 바뀔 수 있습니다.

그래서 JavaScript만으로 빠르게 만드는 것보다 TypeScript를 사용하는 편이 더 안전하다고 생각했습니다.

TypeScript를 쓰면 API 응답 구조, report 필드, policy 상태 같은 값들을 타입으로 관리할 수 있습니다.

API 응답 변경
  -> TypeScript type에서 먼저 감지
  -> 화면 깨짐을 줄일 수 있음

운영 도구에서는 이런 안정성이 꽤 중요합니다.

장애 상황에서 화면이 조용히 깨지면 운영자는 더 혼란스러워질 수 있기 때문입니다.

Vite를 사용한 이유

프론트엔드 개발 환경은 Vite로 구성했습니다.

Vite를 쓴 이유는 단순합니다.

개발 서버가 빠르고, React + TypeScript 구성이 간단하며, build 결과물을 Spring Boot 쪽에 포함시키기도 좋았습니다.

구조는 이렇게 잡았습니다.

frontend 개발 중:
Vite dev server
  -> /api 요청은 Spring Boot 8080으로 proxy

빌드 후:
React build output
  -> Spring Boot target/frontend-dist
  -> 같은 origin에서 Web Console 제공

이렇게 하면 개발할 때는 프론트엔드를 빠르게 수정할 수 있고, 빌드 후에는 Spring Boot Platform이 정적 파일까지 함께 제공할 수 있습니다.

즉, 개발 편의성과 배포 단순성을 같이 가져가려는 구조였습니다.

Bootstrap 5를 선택한 이유

UI 프레임워크는 Bootstrap 5를 사용했습니다.

처음부터 디자인 시스템을 직접 만들 생각은 없었습니다.

이 프로젝트에서 중요한 것은 화려한 UI가 아니라, 운영자가 필요한 정보를 빠르게 확인할 수 있는 화면이었습니다.

Bootstrap은 다음 부분에서 편했습니다.

• table
• card
• badge
• button
• alert
• form
• modal
• responsive layout

RCA report나 policy 상태를 보여줄 때도 badge 형태가 잘 맞았습니다.

예를 들어 조치 위험도를 화면에 표시할 때 이런 식으로 표현할 수 있습니다.

AUTO_SAFE
APPROVAL_REQUIRED
NEVER_AUTO_EXECUTE
MANUAL_INVESTIGATION

운영자는 긴 설명보다 먼저 상태를 빠르게 파악해야 합니다.

그래서 Bootstrap 5는 이 프로젝트의 목적에 잘 맞았습니다.

Console에서 가장 중요했던 화면

Console에서 가장 중요하게 본 것은 RCA report 상세 화면이었습니다.

report 목록은 많은 정보를 보여주기보다, 최근 장애 분석 결과를 빠르게 훑어볼 수 있으면 됩니다.

하지만 상세 화면은 달라야 합니다.

운영자가 실제 판단을 하려면 다음 정보가 필요합니다.

• 어떤 cluster에서 발생했는지
• 어떤 node가 영향을 받았는지
• 어떤 evidence가 수집됐는지
• 어떤 signal이 감지됐는지
• root cause candidate는 무엇인지
• confidence는 어느 정도인지
• 추천 조치의 policy level은 무엇인지
• export 가능한 report인지

이 중에서 특히 중요하게 본 것은 evidence와 policy였습니다.

AI가 포함된 RCA 도구에서는 “AI가 이렇게 말했습니다”보다
“이런 evidence를 바탕으로 이렇게 판단했습니다”가 더 중요합니다.

Spring Boot와 같은 origin으로 묶기

Spring Boot Platform으로 통합하면서 Web Console도 같은 origin에서 제공하는 방향으로 잡았습니다.

개발 중에는 Vite proxy를 사용하고, 배포 시에는 Spring Boot가 정적 파일을 함께 제공하는 구조입니다.

이렇게 하면 CORS나 API base URL 문제를 줄일 수 있습니다.

브라우저
  -> Spring Boot Platform
      -> Web Console
      -> /api/**
      -> /health

운영 도구에서는 이런 단순함이 중요합니다.

프론트엔드 서버와 API 서버가 완전히 분리되어 있으면 배포 설정, 인증 쿠키, CORS, proxy 설정을 따로 관리해야 합니다.

이 프로젝트에서는 아직 대규모 프론트엔드 서비스가 아니라, Platform 안에 포함된 운영 콘솔에 가깝기 때문에 같은 origin 구조가 더 자연스러웠습니다.

Codex를 어떻게 활용했는가

이번 단계에서도 화면의 방향은 직접 잡았습니다.

어떤 정보를 먼저 보여줘야 하는지, report 상세에서 어떤 근거를 보여줘야 하는지, policy를 어떻게 노출해야 하는지는 사람이 판단해야 했습니다.

반면 반복적인 UI 구현은 Codex를 활용했습니다.

사람:
화면 정보 우선순위 결정
운영자 관점의 흐름 설계
policy/evidence 노출 기준 판단
API 응답 구조 검토

Codex:
React component 초안 작성
TypeScript type 정리
API fetch 코드 반복 구현
Bootstrap layout 구성
empty/error state 보강

Codex는 UI 작업에서 꽤 유용했습니다.

하지만 “어떤 화면이 운영자에게 실제로 도움이 되는가”는 직접 고민해야 했습니다.

이 단계에서 중요했던 점

이번 단계에서 중요하게 본 것은 세 가지였습니다.

1. 운영자가 report를 빠르게 이해할 수 있어야 한다
2. TypeScript로 API 응답 구조를 더 안전하게 다뤄야 한다
3. Spring Boot와 같은 origin으로 묶어 배포 구조를 단순하게 가져가야 한다

Web Console은 프로젝트의 얼굴입니다.

하지만 단순히 보기 좋은 화면보다, 장애 상황에서 운영자가 덜 헤매게 만드는 것이 더 중요했습니다.

그래서 화면을 만들 때도 계속 이 기준을 두었습니다.

예쁜 UI보다 판단 가능한 UI가 먼저다.

마무리

이번 단계에서는 Spring Boot Platform 위에 React 19, TypeScript, Vite, Bootstrap 5 기반 Web Console을 다시 구성했습니다.

이 전환으로 Console은 단순 조회 화면에서 조금 더 운영자 중심의 화면으로 바뀌기 시작했습니다.

RCA report, evidence, policy, incident 상태를 더 명확히 보여줄 수 있는 기반이 생겼고, 개발과 배포 구조도 더 단순해졌습니다.

다음 글에서는 Flyway migration, incident, audit event, metric, retention 같은 운영 기능을 묶으면서 이 프로젝트를 더 플랫폼답게 다듬은 과정을 정리해보겠습니다.