프로젝트 소개 본문으로 건너뛰기
QUAKECURRENTPROJECT BRIEF
FULL-STACK DATA PROTOTYPE · CASE STUDY

지진 피드를,
끊겨도 복구되는
데이터 제품으로.

USGS 최근 24시간 지진 피드를 수집·정규화하고, REST 스냅샷과 변경 사건만 알리는 WebSocket 신호로 3D·2D 지도에 연결한 풀스택 프로토타입입니다.

프로토타입 열기구현·검증 로그 보기
01 · PROBLEM / RESPONSE

지도보다 먼저, 실패 경로를 제품 범위에 넣었습니다.

PROBLEM

표시보다 어려운 것은 중복·복구·계약 불일치였습니다.

변경 신호형 지도는 데이터를 그리는 것만으로 끝나지 않습니다. 같은 사건의 중복 적재, 연결 단절 사이의 누락, 서버와 클라이언트 타입의 불일치가 사용 경험을 먼저 무너뜨릴 수 있습니다.

RESPONSE

멱등 저장부터 재연결과 타입 생성까지 한 흐름으로 묶었습니다.

source와 external_id 기반 upsert, sequence 이후 REST catch-up, FastAPI → OpenAPI → TypeScript 자동 검증을 하나의 수직 슬라이스 안에서 연결했습니다.

구현 범위
  • 최근 24시간 지진이라는 수직 슬라이스와 한국어 정보 구조
  • React·MapLibre·deck.gl 기반 데스크톱·모바일 지도 UX
  • FastAPI·PostGIS·Celery·Redis 수집 및 변경 신호
  • OpenAPI TypeScript 생성, 회귀 테스트와 CI 자동 검증
02 · REVIEW EVIDENCE

설명 대신 다시 실행할 수 있는 증거

IDEMPOTENCY0 NEW / SIGNALS2-event fixture 재수집 · 로컬 통합
API TESTS15 PASS버전별 결정론 15 · 통합 3 제외
BROWSER10 / 10데스크톱·모바일 URL 흐름
DRIFT GATES2 / 2FastAPI→OpenAPI→TypeScript
WEB MODEL14 / 14URL 필터 · 지역화 · 시간/깊이
CIPASSPython 3.12·3.13 · container · web
GitHub Actions 확인결함과 수정 증거 전체 보기

위 수치는 로컬 및 공개 CI 검증 결과입니다. 실제 사용자 트래픽, 프로덕션 가용성이나 운영 성능을 의미하지 않습니다.

03 · ENGINEERING DECISIONS

기술 이름보다 선택 기준을 남겼습니다.

D-01

작은 스냅샷은 브라우저에서 필터링

Cycle 02의 로컬 측정에서 응답 스냅샷이 약 45KB여서 API 복잡도를 먼저 늘리지 않았다. 시간·규모·깊이 상태는 URL에 보존해 공유와 새로고침을 같은 경계로 처리했다.

승격 기준 · gzip 250KB 또는 계산 p95 50ms 초과
D-02

전체 데이터 대신 작은 변경 신호

WebSocket에는 사건 본문 대신 ID·operation·sequence·updated_at 변경 메타데이터만 전달한다. 연결이 끊기면 마지막 sequence 이후의 변경을 REST로 복구한다.

REST snapshot + compact WebSocket signal
D-03

서버 계약에서 TypeScript를 생성

FastAPI를 REST 계약의 유일한 원본으로 두고 OpenAPI 스냅샷과 TypeScript 타입을 생성한다. 어느 한쪽만 바뀌면 로컬과 CI가 실패한다.

5 paths · 11 schemas · 446 generated LOC
D-04

같은 커밋은 같은 Python 의존성으로

uv.lock에 직접·전이 의존성과 해시를 고정했다. Python 3.12와 3.13에서 같은 계약과 테스트를 실행하고 컨테이너도 같은 lock을 소비한다.

uv 0.12.0 · Python 3.12 / 3.13
04 · SYSTEM FLOW

원본 피드에서 사용자의 지도까지 이어지는 경계

  1. 01
    USGS60초 조건부 수집
  2. 02
    POSTGIS멱등 upsert·공간 저장
  3. 03
    FASTAPIREST 스냅샷·WS 신호
  4. 04
    OPENAPI TS생성 계약·drift gate
  5. 05
    MAP UI목록·통계·3D/2D 지도
05 · ITERATION LOOP

한 번 만든 뒤 끝내지 않는 작업 방식

  1. 01PROTOTYPE

    최근 24시간 지진 탐색이라는 가장 얇은 수직 슬라이스로 사용자 동선을 먼저 확인했다.

  2. 02PLAN

    중복 수집, 재연결 누락, 계약 불일치를 화면보다 먼저 닫아야 할 실패 경로로 정했다.

  3. 03AUTOPILOT

    수집·타입 생성·잠금 설치·테스트·CI 검증을 반복 가능한 명령과 파이프라인으로 만들었다.

  4. 04REVIEW

    실제 결함과 보류 범위를 숨기지 않고 수정 결과, 실행 링크, 다음 판단 기준과 함께 기록했다.

EXPLICIT BOUNDARIES

완료한 것과 하지 않은 것을 함께 기록합니다.

  • 실시간 재난 경보 서비스가 아닌 개발 프로토타입입니다.
  • API가 없을 때는 내장 데모 스냅샷임을 화면에 표시합니다.
  • 배포·실사용 트래픽·production telemetry는 현재 검증 범위에서 제외했습니다.