ScreenReaderStudio는 웹 페이지나 HTML 코드를 입력하면, 스크린 리더가 어떻게 읽을지를 시각적으로 예측하고 접근성 문제를 진단해 주는 도구입니다. 스크린 리더 환경을 직접 확인하기 어려운 개발자를 위해, 웹 접근성 개선을 직관적이고 효율적으로 지원합니다.

Deployed website | Frontend Repository | Backend Repository

• ScreenReaderStudio
• 📖 Table of Contents
• 🛠 Tech Stacks
  • Client
  • Server
  • Deployment
• 📁 Project Structure
• 🔥 Motivation
• 📋 Features
  • 1. 분석 기능
    • 초기 화면
    • 스크린 리더 대본
    • 접근성 이슈
  • 2. 공유 기능
    • 로그인
    • 공유하기
    • 공유된 결과
• 🏔 Challenges
  • 1. 처음에는 JSX 코드로 접근성 이슈 분석 및 스크린 리더 대본을 생성하려 했으나
    • ❗️문제 정의
      • 1. 실제 컴포넌트 구조의 복잡도
      • 2. 정적 코드 분석의 한계
      • 3. 실제 사용 시나리오와의 괴리
    • 🔧 고민의 흐름
    • ✅ 최종 해결책: URL 기반의 페이지 분석으로 방향 전환
      • 주요 전환 사항
    • ✅ 장점
    • ⚠️ 한계 및 고려 사항
    • 🔚 결론
  • 2. 클라이언트에서는 iframe을 사용하려면 겪는 문제와 내가 선택한 해결책
    • ❗️문제 정의
      • 1. iframe의 보안 정책(CORS, sandbox) 제약
      • 2. 상대 경로 및 리소스 로딩 실패
      • 3. SPA 및 동적 웹사이트의 분석 불가능
    • 🔧 고민의 흐름
    • ✅ 최종 해결책: 서버 측 Headless Browser 렌더링으로 구조 전환
      • 주요 전환 사항
    • ✅ 장점
    • ⚠️ 한계 및 고려 사항
    • 🔚 결론
  • 3. 로딩 시간이 오래 걸릴 때, 사용자의 이탈을 막으려면 어떻게 해야 할까?
    • ❗️문제 정의
      • 1. 분석 시간이 사용자 체감상 길게 느껴짐
      • 2. 분석이 진행 중임을 알리는 UI 요소의 부재
    • 🔧 고민의 흐름
    • ✅ 최종 해결책: Skeleton UI 도입
      • 적용 방식
      • 기술 스택
    • ✅ 장점
    • ⚠️ 한계 및 고려 사항
    • 🔚 결론
  • 4. 서버의 비동기 분석 작업을 사용자에게 어떻게 자연스럽게 연결할까?
    • ❗️문제 정의
    • 🔧 설계 판단
    • ✅ 최종 해결책: 생성, polling, 복구를 하나의 상태 흐름으로 통합
    • 🧪 테스트와 운영 검증
    • ✅ 장점
    • ⚠️ 한계 및 고려 사항
    • 🔚 결론
• 💭 Memoir

프론트엔드는 Next.js App Router를 기반으로 하며, 라우팅과 업무 로직의 책임을 분리하기 위해 도메인 모듈 중심으로 구성했습니다.

src/
├── app/                         # 라우트, 레이아웃, 페이지 조합
├── components/
│   ├── layout/                  # 여러 페이지에서 사용하는 레이아웃 컴포넌트
│   └── ui/                      # 도메인에 의존하지 않는 공통 UI
├── modules/
│   ├── analysis/
│   │   ├── api/                 # 분석 실행, 저장, 조회 API
│   │   ├── components/          # 입력 및 결과 화면
│   │   ├── model/               # Zustand 상태
│   │   ├── constants.ts
│   │   └── types.ts
│   └── auth/
│       ├── api/                 # 사용자 조회, 로그인, 로그아웃 API
│       ├── components/          # 인증 UI
│       ├── AuthProvider.tsx
│       └── types.ts
├── providers/                   # 애플리케이션 전역 Provider
├── shared/
│   ├── api/                     # 공통 API 클라이언트
│   ├── config/                  # 공통 설정과 상수
│   ├── lib/                     # 범용 유틸리티
│   └── types/                   # 공통 타입
└── test/                        # 전역 테스트 설정

public/                           # 이미지와 폰트 등 정적 리소스

• app은 URL 구조와 페이지 조합을 담당하며, 구체적인 업무 로직은 각 도메인 모듈에 둡니다.
• modules는 analysis, auth처럼 서비스의 업무 영역별 API, UI, 상태, 타입을 함께 관리합니다.
• components/ui와 shared는 특정 도메인을 알지 못하는 코드만 포함해 재사용 범위를 명확하게 유지합니다.
• 테스트는 전역 설정을 제외하고 구현 파일과 같은 위치에 배치합니다.

토스의 기술 블로그 게시글 중 우리가 몰랐던 시각 장애인의 UX을 읽다가 다음과 같은 문장을 접했습니다.

“그런데 스크린 리더가 ‘아이콘 하트’라고 읽어주면, 사용자는 이게 찜하기 버튼인지 알기 어려워요.”

이 문장을 통해, 시각장애 사용자에게는 스크린 리더가 읽어주는 한 문장, 한 단어가 곧 UI의 전부일 수 있다는 사실을 다시금 인식하게 되었습니다. 시각 정보 없이 콘텐츠를 해석해야 하는 환경에서, 텍스트 외 요소들이 어떻게 설명되느냐는 곧 UX의 핵심이 될 수 있기 때문입니다.

또한, 이 문구를 읽는 순간, 과거 웹 개발 중 img 태그에 alt 속성을 빠뜨렸을 때 콘솔에서 경고 메시지를 본 기억이 떠올랐습니다. 그 당시에는 단순히 린트 에러처럼 여겼던 그 경고가, 이제는 사용자에게 ‘이 이미지는 무엇인가’를 설명해주는 기능이었음을 깨닫게 된 것 이었습니다.

이와 같은 경험을 통해, 우리는 잘 만들었다고 생각하는 웹 서비스에서도 어떤 사용자에게는 사용하기 어려운 서비스일 수 있다는 점을 체감하게 되었습니다. 하지만 스크린 리더의 동작을 실제로 확인해보는 것은 여전히 어렵고, 개발 도중 혹은 배포 이후에도 즉각적으로 접근하기 힘든 영역이기도 합니다.

따라서, 스크린 리더가 실제로 어떻게 읽어줄지를 시각적으로 예측해주고, 접근성 문제를 자동으로 진단해주는 도구가 있다면 분명 도움이 될 것이라는 문제의식이 생겼습니다.

이러한 계기로, 개발자와 디자이너가 스크린 리더 환경을 별도의 설정 없이 손쉽게 파악하고, 접근성 이슈를 빠르게 인지하고 개선할 수 있도록 돕는 도구인 ScreenReaderStudio를 개발하게 되었습니다.

초기 기획 단계에서 ScreenReaderStudio는 사용자가 입력한 페이지 URL이 아닌, 개별 컴포넌트의 JSX 코드만을 기반으로 접근성 분석 및 스크린 리더 대본을 생성하는 구조를 고민했습니다. 이는 개발자 친화적인 인터페이스를 제공하며, Storybook이나 디자인 시스템 같은 문맥에서 개별 컴포넌트 단위로 접근성을 확인할 수 있도록 하기 위함이었습니다.

이를 위해 Babel을 사용해 JSX 코드를 JavaScript AST로 변환하고, @babel/traverse로 트리를 순회하며 접근성 이슈를 탐지하는 분석 로직을 구성하려 했습니다.

• 실제 서비스에 사용되는 React 컴포넌트는 단순한 <button>이나 <img> 수준의 요소가 아닌 경우가 대부분이며, 수많은 외부 라이브러리, 중첩된 컴포넌트, 동적 props, context 의존 등이 얽혀 있는 구조입니다.
• 이로 인해 Babel로 추출한 AST만으로는 컴포넌트의 실제 렌더링 결과를 예측하기 어렵고, 의미 있는 접근성 분석 결과를 도출하는 데 한계가 있었습니다.

• 접근성 분석은 본질적으로 렌더링된 DOM의 구조, 시멘틱 요소, 포커스 흐름 등 실행 시점의 상태에 의존합니다.
• JSX 코드를 정적으로 분석하는 것은 컴파일 결과나 브라우저 환경에서 실제로 생성된 DOM과 다를 수 있으며, 분석 정확도가 낮아질 수밖에 없습니다.
• 예를 들어 조건부 렌더링, 사용자 상호작용에 따른 변경 사항 등은 정적 분석으로는 포착이 불가능합니다.

• 실무에서는 개별 컴포넌트가 아닌, 전체 페이지 단위의 접근성 품질이 중요합니다.
• 예를 들어, 버튼이 존재하더라도 그 버튼이 어디에 위치해 있는지, 어떤 시멘틱 구조 내에 포함되어 있는지, 페이지 내에서 어떤 역할을 수행하는지 등은 페이지 전반의 문맥을 고려해야 분석이 가능합니다.
• 단일 컴포넌트만 따로 떼어내 접근성 진단을 한다는 것은 실질적인 분석 시나리오와 맞지 않음을 점차 깨닫게 되었습니다.

초기에는 개발자 관점에서 접근하기 쉬운 인터페이스를 제공하고자 JSX 코드 기반의 분석을 시도했지만, 점차 접근성 분석의 본질은 정적 코드 분석이 아닌 실제 사용자 환경에서의 인터랙션 가능성, 화면 구조, 콘텐츠 흐름을 바탕으로 해야 한다는 사실을 직시하게 되었습니다.

그 결과, "코드가 아닌 웹페이지 전체를 대상으로 분석해야 한다"는 관점을 받아들이게 되었고, “URL 기반 접근성 분석” 이라는 방향으로 전환하게 되었습니다.

접근성 분석의 정확성과 실효성을 보장하기 위해, JSX 코드 대신 전체 웹페이지를 Headless Browser로 렌더링하고 분석하는 구조로 변경했습니다. (→ 2. 클라이언트에서는 iframe을 사용하려면 겪는 문제와 해결 방법 참고)

• Babel 기반 JSX 분석 폐기
• 서버 측에서 Puppeteer로 페이지를 실제로 렌더링한 후, axe-core를 통해 실시간 DOM 기반 접근성 분석 수행
• 컴포넌트 단위가 아닌 페이지 전체 단위로 스크린 리더 대본과 이슈를 생성하는 구조 채택

• 실제 환경 기반 분석: 렌더링 이후의 DOM을 기준으로 하기 때문에, 조건부 렌더링, 동적 콘텐츠도 정확하게 분석 가능
• 정확도 향상: 코드 구조가 복잡하더라도 최종 출력된 HTML에 기반해 분석하므로, 누락 없이 이슈를 포착할 수 있음
• 개발자 실무 흐름과 정합: 실제 접근성 테스트는 페이지 단위로 진행되며, 이 흐름과 구조적으로 일치

• 개별 컴포넌트 테스트는 불가: 컴포넌트 단위에서의 마이크로한 분석은 불가능하며, 별도의 storybook 환경 등을 분석 대상으로 삼아야 함
• 개발 초기 아이디어와의 괴리: 초기 기획과는 다소 결이 달라졌으나, 최종 사용자 요구와 분석 신뢰도 측면에서 훨씬 효과적인 구조로 진화했다고 판단

JSX 코드 기반의 정적 분석은 기술적으로 시도해볼 수 있는 접근이었지만, 실제 웹 접근성 분석이라는 목적에는 부합하지 않는 방법이었습니다. 결과적으로 우리는 “코드를 분석하는 것이 아니라, 사용자에게 보여지는 결과를 분석하는 것이 본질”이라는 점을 깨달았습니다.

이러한 반성과 판단을 통해, ScreenReaderStudio는 코드 기반 분석이 아닌 URL 기반 페이지 분석 중심의 아키텍처로 재설계되었고, 이는 이후 iframe, 서버 렌더링, Skeleton UI 도입 등 모든 기술 결정의 기반이 되었습니다. 이 과정은 단순한 기술 변경이 아닌, 문제의 본질을 다시 정의하고 구조적으로 대응한 전환의 시작점이었습니다.

ScreenReaderStudio는 초기에는 사용자가 입력한 웹페이지 URL을 클라이언트 측 iframe에 로드하여, 접근성 분석 및 스크린 리더 대본을 생성하려는 방향을 검토했습니다. 이는 서버 인프라를 줄이고, 빠른 분석 피드백을 제공하기 위한 가볍고 직관적인 아키텍처를 지향한 선택이었습니다.

iframe을 통해 실제 페이지를 불러오고, DOM을 분석하거나 음성 대본을 생성하는 방식을 고려했으나, 보안 정책과 브라우저 동작 원리에 의해 치명적인 한계를 갖고 있다는 사실을 점차 깨닫게 되었습니다.

• 외부 URL을 iframe에 로드할 경우, CORS 및 브라우저의 sandbox 제한으로 인해 DOM 접근이 차단되고, 페이지 내부의 JS 동작도 제약됩니다.
• 특히 sandbox="allow-scripts allow-same-origin"은 보안상 위험하다고 판단되어 일부 브라우저에서 강제 제한되며, 외부 API 요청(fetch/XHR) 등은 대부분 CORS 에러로 실패합니다.

Access to XMLHttpRequest at 'https://ko.wikipedia.org/...' from origin 'http://localhost:3000' has been blocked by CORS policy

• iframe 내부에서 불러오는 CSS, 이미지, JS 등의 상대 경로 리소스가 깨지거나 404 오류가 발생하는 문제가 빈번하게 발생했습니다.
• <base href="..."> 태그를 주입해 상대 경로 문제를 보완하려 했으나, 이는 HTML 문서에 국한되며 JS의 네트워크 요청에는 영향을 주지 않아 근본적인 해결책이 되지 못했습니다.

• iframe은 단순한 정적 HTML은 로드할 수 있지만, JavaScript 기반의 SPA 구조나 조건부 렌더링이 많은 페이지는 클라이언트 측에서 완전하게 구성된 DOM을 추출할 수 없습니다.
• 이로 인해 분석의 정확성이 떨어지며, 실제 사용자 시나리오와 괴리된 결과를 초래했습니다.

초기에는 iframe을 통해 웹페이지를 직접 브라우저에 불러오고, 그 상태에서 접근성 분석을 수행하는 것이 가장 빠르고 직관적인 방법이라고 판단했습니다. 그러나 점차 분석이 실패하는 사례들이 누적되면서, CORS, sandbox, 자원 로딩 등 다양한 보안 정책과 브라우저의 기본 동작 원리에 의해 클라이언트 측에서 외부 페이지를 안전하게 다루는 것이 구조적으로 불가능하다는 사실을 인식하게 되었습니다.

“그렇다면 어떻게 해서 브라우저는 우리가 iframe으로 불러온 외부 페이지를 이렇게 강하게 보호할 수 있는가?”라는 의문에서 출발해, 우리는 웹의 보안 모델을 더 깊이 조사하기 시작했습니다. 이 과정에서 브라우저는 사용자의 보안을 위해 외부 콘텐츠에 대한 자바스크립트 접근을 철저히 제한하도록 설계되어 있으며, 특히 클라이언트 환경에서는 보안 위협(CSRF, XSS 등)을 막기 위해 의도적으로 많은 기능이 봉인되어 있다는 사실을 이해하게 되었습니다.

하지만 조사 도중 발견한 흥미로운 사실은, 서버에서는 이런 제약이 존재하지 않는다는 점이었습니다. 서버에서는 브라우저처럼 보안 상의 이유로 요청을 제한하지 않으며, Puppeteer와 같은 Headless Browser를 통해 실제 브라우저 환경을 에뮬레이션하여 페이지를 로드하고 분석할 수 있습니다. 서버는 동일 출처 정책이나 CORS를 적용받지 않기 때문에, 클라이언트에서 차단되던 외부 요청이나 DOM 접근도 자유롭게 가능합니다.

결과적으로 우리는 “웹페이지를 클라이언트가 아닌 서버에서 렌더링하고 분석해야 한다”는 방향으로 전환하게 되었고, 이는 단순한 기술 스택 변경이 아니라, 웹의 보안 모델을 이해한 끝에 내린 구조적 전환이었습니다.

iframe 기반 접근의 한계를 극복하기 위해, 서버에서 Headless Chrome(Puppeteer)을 통해 페이지를 실제로 렌더링하고, axe-core를 통해 DOM을 분석하는 구조로 전환했습니다.

• 클라이언트 iframe 접근 방식 폐기
• 서버에서 Puppeteer를 통해 페이지 로딩 및 JavaScript 실행
• 분석 스크립트(axe-core) 주입 후, 실시간 DOM 구조 기반 접근성 진단 수행
• 분석 결과 및 스크린 리더 대본을 클라이언트로 전송하여 시각화

• 보안 정책 우회 가능: 서버에서 직접 외부 페이지를 요청하고 분석하므로, CORS나 sandbox 등의 브라우저 보안 정책에 영향을 받지 않습니다.
• 동적 콘텐츠 지원: JavaScript로 생성되는 SPA 페이지, 조건부 렌더링 등도 완전히 분석 가능
• 정확도 향상: 렌더링이 완료된 DOM을 기준으로 분석하므로, 실제 사용자 경험과 일치하는 결과를 도출
• 페이지 문맥 인식 가능: 전체 구조, 시멘틱 계층, 상호작용 흐름 등을 바탕으로 한 의미 있는 분석 수행 가능

• 서버 자원 소모: Puppeteer는 Chrome 인스턴스를 띄우기 때문에, CPU/메모리 소모가 높고 동시 요청 처리에 제약이 있습니다.
• 서버리스 환경의 제약: Vercel, Netlify 등 일부 플랫폼은 Puppeteer 실행에 제약이 있어, Railway 등 별도 인프라 필요
• 분석 속도 이슈: 렌더링과 분석에 수 초 이상이 소요될 수 있어, 사용자 피드백과 UX 설계가 반드시 병행되어야 함

iframe을 활용한 클라이언트 기반 분석은, 초기에는 가장 단순하고 효과적인 방법처럼 보였으나, 보안 정책(CORS/sandbox)과 브라우저 환경 제약으로 인해 구조적으로 실현 불가능한 방법이었습니다.

우리는 “브라우저는 외부 페이지를 보호하려는 방향으로 설계되어 있다”는 웹 보안의 본질을 마주하게 되었고, 분석을 클라이언트가 아닌 서버에서 수행해야 한다는 명확한 판단에 도달하게 되었습니다.

결국 ScreenReaderStudio는 iframe 기반 분석이 아닌, 서버 측 Headless Browser + 접근성 분석 엔진(axe-core) 조합을 중심으로 구조를 재설계했으며, 이는 단순한 기술 스택 변경을 넘어 웹 보안 모델에 대한 이해를 바탕으로 한 구조적 전환의 결과였습니다.

ScreenReaderStudio는 사용자가 입력한 웹페이지를 서버 측에서 Headless Browser로 렌더링하고, DOM을 기반으로 axe-core를 통해 접근성 분석 및 스크린 리더 대본을 생성하는 구조입니다. 이러한 분석 과정은 웹페이지의 복잡도와 네트워크 상태에 따라 수 초 이상의 시간이 소요될 수 있습니다. 이는 정적인 분석 툴과는 달리 브라우저 수준의 렌더링을 포함하기 때문입니다.

초기에는 결과 화면에 접근성 이슈와 스크립트가 모두 준비된 이후에만 결과 UI를 보여주는 구조였습니다. 하지만 분석 로직이 실행되고 있다는 피드백이 사용자에게 전혀 전달되지 않는다는 치명적인 UX 문제가 존재했습니다. 사용자 입장에서는 “버튼을 눌렀는데 아무런 반응이 없다”는 인상을 받을 수 있으며, 이로 인해 페이지를 이탈하거나 다시 요청을 보내는 불필요한 행위가 발생할 수 있습니다.

• Puppeteer가 실행되고 외부 웹페이지가 렌더링된 후 axe-core가 분석을 수행하는 데 걸리는 시간은 일반적으로 3~6초, 복잡한 웹페이지의 경우 10초 이상까지 소요될 수 있습니다.
• 결과가 준비되기 전까지 아무런 시각적 변화가 없기 때문에, 사용자는 서비스가 멈췄거나 실패했다고 오해할 가능성이 높습니다.

• 초기 구현에서는 분석 중임을 알리는 spinner나 로딩 메시지, 또는 페이지 구성 요소의 placeholder가 전혀 존재하지 않았습니다.
• 텍스트 기반의 단순 안내("분석 중입니다...")만 존재했는데, 이는 시각적으로 너무 약하고 사용자 경험을 향상시키기엔 부족했습니다.

단순한 텍스트 로딩 메시지나 spinner 아이콘 하나로는 해결이 어렵다고 판단했습니다. 이 문제는 단순히 "로딩이 보이지 않는다"는 UI 문제를 넘어서, 사용자에게 "서비스가 현재 제대로 작동 중이다" 라는 심리적 확신을 줘야 하는 문제였기 때문입니다.

특히 ScreenReaderStudio의 경우, 분석 결과가 나타나기 전까지는 화면에 아무런 콘텐츠가 없기 때문에, 분석 결과의 형태를 예상 가능하게 시각적으로 제공해줄 필요가 있었습니다.

위 문제를 해결하기 위해, 결과 화면의 최종 분석 결과 레이아웃을 미리 흉내 내는 Skeleton UI를 도입했습니다.

Skeleton UI는 분석이 진행되는 동안에도 사용자에게 화면 구성의 윤곽을 먼저 보여줌으로써, 결과가 곧 제공될 것이라는 기대감을 유지시켜주는 전략적인 UI 패턴입니다.

• 분석 결과가 아직 도착하지 않았을 때, 로딩 상태를 감지하여 Skeleton UI를 렌더링합니다.
• 결과 리스트(분석된 DOM 구조 + 문제 항목 + 스크린 리더 대본)의 형태를 모방하여, 다음과 같은 skeleton 컴포넌트들을 구현했습니다:
  • 스크린 리더 대본 preview 영역 → 긴 회색 블록
  • 접근성 문제 리스트 → 리스트 형태의 작은 skeleton 블럭 반복
  • 섹션별 구분 헤더 → 약간 어두운 색조의 사각형

• TailwindCSS의 animate-pulse와 bg-gray-200 등의 유틸리티 클래스를 활용해 최소한의 CSS로 Skeleton 효과를 구현
• Skeleton 컴포넌트는 기존 컴포넌트와 동일한 레이아웃 구조를 유지하여 UI 전환이 부드럽게 일어나도록 설계

• 사용자 피드백 개선: 로딩 중에도 서비스가 작동 중이라는 신호를 명확히 전달할 수 있습니다.
• 이탈률 감소: 사용자 입장에서 “기다릴 가치가 있는 상태”라는 신호를 받게 되어 조기 이탈을 방지합니다.
• 전환 자연화: Skeleton → 실제 데이터로의 전환이 시각적으로 자연스러워 UX 일관성 유지합니다.
• 심리적 체감 시간 단축: 분석 결과를 기다리는 동안 실제보다 더 빠르게 결과가 도착했다고 느끼는 효과를 줄 수 있습니다.

• Skeleton은 가짜 데이터이기 때문에, 결과 구조가 자주 변경되면 Skeleton 구조도 함께 유지보수가 필요합니다.
• Skeleton UI도 과하게 복잡하면 오히려 렌더링에 부담을 주거나 사용자 혼란을 유발할 수 있으므로, 최소한의 형태로 간결하게 구성하는 것이 중요합니다.
• 초기 페이지 로딩이 빠르더라도 네트워크 지연이나 서버 부하가 발생하는 경우를 대비해 Skeleton은 항상 fallback으로 유지해야 합니다.

로딩이 길어질 수밖에 없는 구조적 특성을 가진 서비스에서는, 단순한 스피너나 텍스트로는 부족합니다. 사용자에게 분석이 진행되고 있다는 명확한 피드백을 제공하고, 기대감을 유지시키기 위한 시각적 구조가 필요합니다.

이러한 UX 문제를 해결하기 위해 Skeleton UI를 도입함으로써, 분석 과정의 신뢰도와 사용자 경험을 크게 향상시킬 수 있었습니다. 이 결정은 단순한 디자인 변경이 아닌, 사용자 이탈을 막고 서비스 품질을 높이기 위한 전략적 UI 최적화였습니다.

기존 프론트엔드는 POST /api/analysis/perform 요청 하나를 보내고 최대 120초 동안 결과를 기다렸습니다. 이 방식에서는 HTTP 연결이 분석 작업 그 자체였기 때문에 탭을 새로고침하거나 네트워크가 잠시 끊기면 진행 중인 작업을 다시 찾을 방법이 없었습니다. 서버가 분석을 계속하고 있어도 화면에는 오류만 남을 수 있었고, 사용자가 다시 분석 버튼을 누르면 고비용 Puppeteer 작업이 중복 생성될 가능성도 있었습니다.

Skeleton UI는 기다리는 동안의 시각적 불안은 줄여주었지만, 실제 진행 단계, 취소 상태, 새로고침 복구, 안전한 재시도까지 해결하지는 못했습니다. 서버가 분석을 비동기 작업으로 전환함에 따라 프론트엔드도 단순한 요청·응답 코드가 아니라, 오래 살아 있는 작업의 상태를 일관되게 관리하도록 다시 설계했습니다.

• 서버에는 작업이 생성됐지만 202 Accepted 응답을 받기 전에 네트워크가 끊길 수 있습니다.
• 이때 같은 생성 요청을 그대로 재시도할 수 있어야 하며, 사용자가 명시적으로 “다시 시도”를 선택했을 때는 새로운 작업을 만들어야 합니다.

• 사용자가 새 분석을 시작했는데 이전 polling 응답이 늦게 도착하면 새 화면을 오래된 결과로 덮을 수 있습니다.
• queued, running, succeeded, failed, cancelled 상태마다 종료 조건과 후속 동작이 다르므로 하나의 명확한 상태 흐름이 필요했습니다.

• 진행 중인 작업을 복구하려면 jobId뿐 아니라 서버가 요구하는 접근 토큰과 선택한 스크린 리더 정보도 필요합니다.
• 반대로 사용자가 입력한 URL이나 HTML 전체를 브라우저 저장소에 남기는 것은 피해야 했습니다.

• “로딩 중”이라는 한 문장만으로는 대기열에 있는지, 페이지를 불러오는지, 분석 중인지 알 수 없습니다.
• 취소 버튼을 누른 직후 로딩 화면을 없애면 실제 서버 작업이 취소됐는지 알 수 없고, 반대로 계속 같은 문구를 보여주면 버튼이 작동하지 않은 것처럼 느껴집니다.

실시간 전달 방식으로 SSE나 WebSocket도 고려할 수 있었지만, 첫 구현은 서버가 안내한 간격으로 상태를 조회하는 polling을 선택했습니다. 현재 배포 구조에서 프록시와 장시간 연결을 추가로 관리하지 않아도 되고, 새로고침 후 동일한 조회 API를 호출하는 것만으로 복구할 수 있기 때문입니다.

프론트엔드의 전체 흐름은 다음과 같습니다.

분석 버튼
   │
   ├─ 접근 토큰 + 멱등성 키 생성
   ▼
POST /api/analysis/jobs ──▶ 202 { jobId, pollAfterMs }
   │
   ├─ sessionStorage에 복구 정보 저장
   ├─ GET /api/analysis/jobs/:jobId 반복 조회
   │      queued → running → succeeded / failed / cancelled
   │
   ├─ succeeded: GET /result → 기존 ResultViewer에 연결
   ├─ failed: 오류별 복구 안내와 재시도
   └─ cancelled: 서버 확정 후 로딩 종료

작업의 네트워크 생명주기와 React 컴포넌트의 렌더링 생명주기를 분리하고, Zustand store가 생성부터 완료까지 한 작업의 소유권을 갖도록 했습니다.

Web Crypto API의 crypto.getRandomValues로 각각 32바이트, 즉 256비트 난수를 만들어 Base64URL 문자열로 변환했습니다.

• X-Analysis-Job-Token: 상태·결과 조회, 취소, 공유에 사용하는 작업 접근 토큰
• Idempotency-Key: 생성 응답 유실 시 같은 작업을 안전하게 다시 받기 위한 키

작업 생성 요청이 네트워크 오류로 실패하면 같은 입력과 두 비밀값을 유지한 채 지수 backoff로 최대 3회 재시도합니다. 반면 오류 화면에서 사용자가 명시적으로 다시 시도하면 새 비밀값을 생성하므로 이전 작업을 재사용하지 않고 새로운 분석을 시작합니다.

useAnalysisStore에는 기존 결과 데이터와 함께 아래 상태를 추가했습니다.

• jobId, jobAccessToken, jobStatus, jobStage
• isLoading, isCancelling, elapsedSeconds
• 재시도에 사용할 lastRequest

작업마다 별도의 AbortController를 만들고 현재 controller와 일치하는 응답만 store에 반영합니다. 새 분석이나 공유 결과 표시가 시작되면 이전 controller를 중단하며, 늦게 도착한 이전 polling 응답이 최신 화면을 덮지 못하게 했습니다.

작업 생성 응답의 pollAfterMs와 이후 상태 응답의 값을 다음 조회 간격으로 사용합니다. 현재 서버 기본값은 2초입니다. polling 중 일시적인 네트워크 TypeError가 발생하면 간격을 지수적으로 늘리며 최대 3회 재시도하고, 서버가 명시적으로 반환한 API 오류는 즉시 사용자용 오류 상태로 변환합니다.

상태별 동작은 명확히 분리했습니다.

작업이 생성되면 jobId, 접근 토큰, 생성 시각, 선택한 스크린 리더만 sessionStorage에 저장합니다. 원본 URL이나 HTML은 저장하지 않습니다.

AccessibilityAnalyzer가 마운트될 때 resumeAnalysis()를 호출해 저장된 작업을 즉시 조회하고, 아직 진행 중이면 같은 polling 흐름을 다시 시작합니다. 성공, 실패, 취소가 확정되면 저장 정보를 삭제합니다. 따라서 진행 중인 작업은 같은 탭에서 새로고침해도 복구되지만, 완료 결과를 새로고침 후 영구 복원하는 용도는 아닙니다.

기존 Skeleton 레이아웃은 유지하면서 서버 단계마다 안내 문구를 연결했습니다.

화면에는 문구와 경과 초를 표시하고, 로딩 컨테이너에는 aria-busy="true"와 aria-live="polite"를 적용했습니다. 스크린 리더 전용 텍스트에도 같은 단계와 경과 시간을 제공해 시각적 Skeleton만으로 정보를 전달하지 않도록 했습니다.

사용자가 취소 버튼을 누르면 DELETE /api/analysis/jobs/:jobId를 호출하고 버튼을 취소 중... 상태로 비활성화합니다. 실행 중 작업은 서버 worker가 취소 신호를 확인할 때까지 짧은 시간이 걸릴 수 있으므로, 프론트엔드는 즉시 성공으로 간주하지 않고 polling을 계속해 cancelled가 확정된 뒤 종료합니다.

기존 분석 오류에 아래 비동기 작업 오류를 추가했습니다.

• JOB_EXPIRED: 보관 기간이 끝났으므로 분석 대상을 다시 제출하도록 안내
• JOB_NOT_FOUND: 저장된 작업을 찾을 수 없으므로 새 분석을 안내
• JOB_NOT_READY: 결과가 아직 준비되지 않았으므로 잠시 후 재시도 안내
• IDEMPOTENCY_CONFLICT: 새로운 작업으로 다시 시작하도록 안내

오류 코드마다 사용자용 메시지, 복구 방법, 재시도 가능 여부를 함께 정의해 HTTP 상태 코드가 그대로 UI에 노출되지 않게 했습니다.

분석이 성공한 로컬 작업이고 로그인한 경우에만 공유 버튼을 표시합니다. 공유 시 { jobId }와 X-Analysis-Job-Token만 서버에 보내며, 접근성 결과·페이지 콘텐츠·대본은 다시 전송하지 않습니다. 서버가 저장된 완료 결과를 검증해 공유 데이터를 만들기 때문에 payload가 작아지고 클라이언트의 결과 변조 가능성도 줄었습니다.

• Zustand store 테스트에 작업 생성 후 polling, 성공 결과 조회, 취소, 네트워크 재시도, 새로고침 복구, 오래된 작업 정리를 추가했습니다.
• 전체 프론트엔드 38개 테스트와 production build를 통과했습니다.
• Vercel preview에서 먼저 배포 결과를 확인한 뒤 production으로 승격했습니다.
• 이전 배포를 가리키던 production alias를 확인하고 최신 배포로 연결한 뒤, 실제 HTML과 JavaScript bundle에 새 진행 안내, 작업 API 경로, 인증 헤더가 포함됐는지 확인했습니다.
• Vercel 운영 페이지에서 Render API로 작업을 생성하고 결과를 받는 흐름을 확인했습니다.

• 새로고침에 강한 분석 흐름: 같은 탭에서는 진행 중인 작업을 다시 찾아 이어서 볼 수 있습니다.
• 안전한 생성 재시도: 응답 유실이 중복 Puppeteer 실행으로 이어지지 않습니다.
• 명확한 진행 정보: 대기, 브라우저 준비, 페이지 로딩, 분석, 결과 정리 단계를 구분합니다.
• 실제 취소 상태 반영: 버튼 클릭과 서버의 취소 확정을 구분해 잘못된 완료 처리를 막습니다.
• 접근 가능한 피드백: 보이는 문구뿐 아니라 aria-live, aria-busy, 스크린 리더 전용 텍스트로 진행 상태를 전달합니다.
• 기존 결과 UI 재사용: 성공 이후에는 이전의 ResultViewer 데이터 구조를 그대로 사용해 비동기 전환의 영향 범위를 줄였습니다.

• sessionStorage를 사용하므로 다른 탭이나 다른 기기에서는 작업을 이어볼 수 없습니다.
• 완료 후 복구 정보를 삭제하므로 성공 결과를 새로고침 뒤 복원하지 않습니다. 장기 보관은 로그인 사용자의 공유 기능처럼 별도 저장 흐름을 이용해야 합니다.
• polling은 서버와 브라우저 모두에 반복 요청 비용을 만들고, 기본 2초만큼 상태 반영이 늦을 수 있습니다. 사용량이 증가하면 가시성에 따라 polling을 늦추거나 SSE를 검토할 수 있습니다.
• 실행 중 취소는 서버 heartbeat 주기에 영향을 받아 버튼을 누른 뒤 확정까지 시간이 걸릴 수 있습니다.
• 브라우저 저장소의 접근 토큰은 같은 origin에서 실행되는 JavaScript가 읽을 수 있으므로 XSS 방지와 외부 스크립트 관리가 계속 중요합니다.

프론트엔드의 비동기 전환은 API 경로를 바꾸는 작업에 그치지 않았습니다. 생성 요청의 멱등성, 장시간 polling, 경쟁 상태 방지, 새로고침 복구, 취소 확인, 오류 복구, 접근성 있는 진행 안내를 하나의 사용자 흐름으로 연결해야 했습니다.

그 결과 서버 작업은 브라우저 연결과 독립적으로 실행되고, 사용자는 그 작업의 현재 상태를 이해하며 필요할 때 취소하거나 복구할 수 있게 되었습니다. 또한 기존 결과 화면과 공유 기능을 유지하면서 비동기 프로토콜을 도입해, 앞으로 SSE나 전용 작업 화면으로 확장할 수 있는 기반을 마련했습니다.

이번 프로젝트를 진행하며 혼자서 서비스의 처음부터 끝까지 책임지는 일이 얼마나 큰 도전인지를 깊이 느꼈습니다. 어떤 컴포넌트가 필요할지부터 시작해서 화면 구성을 어떻게 할지, 또 어떻게 사용자에게 전달할지까지 전 과정을 스스로 판단하고 선택해야 했습니다. 그동안 당연하게 여겼던 의사결정조차 스스로 내리려니 더 많은 고민이 필요했고, 작은 선택 하나에도 결과가 달라질 수 있다는 점에서 많은 부담을 느끼기도 했습니다. 하지만 동시에, 내가 직접 모든 흐름을 설계하고 구현해냈다는 점에서 큰 성취감과 자신감을 얻을 수 있었습니다.

프로젝트 중에는 기술적인 도전도 많았습니다. 그동안 문서로만 접했던 도구나 라이브러리를 실전에서 사용해보며, 단순히 사용법을 익히는 것을 넘어 ‘이 도구가 어떤 문제를 해결하기 위한 것인가’를 이해하려고 노력했습니다. 특히 처음으로 Next.js를 제대로 사용해 보면서, 프레임워크에 대한 표면적인 이해를 넘어, SEO, App Router, SSR 등의 개념을 직접 적용하고 경험할 수 있었습니다. 기술을 배우는 것 자체보다 중요한 건 ‘문제를 해결하기 위한 적절한 수단으로 기술을 고르는 능력’이라는 점을 체감한 순간이기도 했습니다.

개발을 진행하면서 사용자 경험에 대해 더 깊이 고민하게 된 것도 중요한 변화였습니다. 시각장애인이 웹을 사용하는 방식을 시뮬레이션하는 과정에서, 우리가 너무 쉽게 간과하고 있던 요소들이 실제 사용자에게는 얼마나 큰 장벽이 되는지를 실감할 수 있었습니다. 단순히 작동하는 UI를 만드는 것을 넘어서, 누구에게나 접근 가능한 UI를 만들기 위한 기준과 태도가 필요하다는 것을 배웠습니다. 보이지 않는 정보를 어떻게 전달할 것인지, 화면에 보이는 요소들을 어떻게 더 명확하게 설명할 수 있을지를 고민하면서, 접근성은 선택이 아니라 기본이 되어야 함을 깨달았습니다.

이번 프로젝트는 단순히 기술적인 성장에 그치지 않고, 개발자로서 가져야 할 문제 해결 태도, 사용자 중심의 시각, 그리고 더 나은 서비스를 만들기 위한 책임감을 다지는 계기가 되었습니다. 끝으로, 내가 만들고 있는 서비스가 단지 기능적으로 완성되는 것을 넘어서, 누군가에게 실질적인 도움이 될 수 있다는 믿음이 생긴 것이 가장 큰 수확이었습니다.