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

Kubernetes Cluster Infra RCA Platform 개발 기록 8편

---

지난 글에서는 FastAPI Backend를 Spring Boot 3.5.15와 Java 21 기반 Platform으로 통합한 이유를 적었다.

이번에는 그 위에 Web Console을 다시 구성한 과정을 다룬다.

초기 Console은 RCA report를 화면에서 조회하는 데 집중했다.

기능이 늘면서 어떤 정보를 먼저 보여줄지 다시 정해야 했다.

장애 상황에서 원인 후보, 근거, 조치 위험도를 빠르게 찾을 수 있는 화면을 만들려고 했다.

이 기준으로 React 19, TypeScript, Vite, Bootstrap 5 기반의 Console을 구성했다.

---

왜 React와 TypeScript였나

Console에서 다룰 화면과 데이터가 늘고 있었다.

당시 필요한 항목은 다음과 같았다.

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

화면마다 데이터 구조가 달랐고, API 응답도 개발 중에 바뀔 수 있었다.

그래서 TypeScript로 응답과 화면 상태의 타입을 관리하기로 했다.

report 필드와 policy 상태를 타입으로 정의하면 변경이 화면에 미치는 영향을 확인하기 편했다.

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

장애 중에 화면까지 조용히 깨지면 상황을 파악하기 더 어려워진다.

응답 구조가 달라졌을 때 개발 과정에서 확인할 수 있는 지점을 두고 싶었다.

---

Vite를 사용한 이유

개발 환경은 Vite로 구성했다.

개발 서버가 빠르고 React + TypeScript 설정이 간단했다. 빌드 결과물을 Spring Boot에 포함시키기도 수월했다.

개발과 배포 경로를 다음처럼 나눴다.

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

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

개발 중에는 Vite에서 화면을 수정하고, 빌드 후에는 Spring Boot가 정적 파일을 함께 제공하도록 했다.

---

Bootstrap 5를 선택한 이유

UI 구성에는 Bootstrap 5를 사용했다.

이 단계에서 디자인 시스템을 따로 만들 계획은 없었다.

운영 정보를 표, 카드, 상태 표시로 일관되게 보여주는 데 집중했다.

주로 사용한 요소는 다음과 같다.

• 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에서 가장 중요했던 화면

RCA report 상세 화면에 가장 많은 비중을 뒀다.

목록에서는 최근 분석 결과를 훑고, 상세에서는 판단에 필요한 근거를 확인하도록 나눴다.

상세 화면에 필요한 정보는 다음과 같았다.

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

이 중 evidence와 policy를 빠뜨리지 않으려고 했다.

원인 후보가 어떤 근거에서 나왔는지, 제안된 조치가 어느 수준의 위험으로 분류됐는지 함께 보여줘야 했다.

---

Spring Boot와 같은 origin으로 묶기

Web Console과 API는 Spring Boot의 같은 origin에서 제공하기로 했다.

개발 중에는 Vite proxy를 쓰고, 배포할 때는 Spring Boot가 정적 파일을 제공하는 구조다.

CORS와 API base URL을 따로 맞춰야 하는 부분을 줄이려는 선택이었다.

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

프론트엔드 서버를 분리하면 배포 설정, 인증 쿠키, CORS, proxy 설정도 각각 관리해야 했다.

당시에는 Platform 내부 운영 콘솔이었으므로 같은 origin으로 묶는 편이 적합하다고 판단했다.

---

Codex를 어떻게 활용했는가

화면의 정보 우선순위는 직접 정했다.

report 상세에서 보여줄 근거와 policy 노출 방식도 직접 검토했다.

반복되는 UI와 API 호출 코드에는 Codex를 활용했다.

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

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

컴포넌트 초안과 타입, 오류 상태 코드를 작성하는 시간을 줄일 수 있었다.

그 결과물이 실제 화면에서 필요한 정보를 보여주는지는 직접 확인했다.

---

이 단계에서 중요했던 점

작업 기준은 세 가지였다.

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

장애 상황에서 필요한 정보에 도달하는 순서를 기준으로 화면을 검토했다.

---

마무리

Spring Boot Platform 위에 React 19, TypeScript, Vite, Bootstrap 5 기반 Web Console을 다시 구성했다.

조회 화면을 목록과 상세로 나누고, 근거와 상태를 확인하는 흐름을 정리했다.

RCA report, evidence, policy, incident를 보여줄 기반이 생겼고 개발과 배포 경로도 함께 정리됐다.

다음 글에서는 Flyway migration, incident, audit event, metric, retention을 다룬다.