JaneJase (자네자세)

JaneJase — AI 기반 실시간 자세 교정 웹 서비스

웹캠을 통해 사용자의 자세를 실시간으로 분석(MediaPipe)하고, 거북목 및 신체 불균형을 감지하여 즉각적인 피드백을 제공하는 헬스케어 서비스입니다.

1. 시스템 아키텍처 (System Architecture)

클라이언트 중심의 AI 처리로 서버 부하를 최소화하고, FastAPI 백엔드로 안정적인 데이터 관리를 수행합니다. 

flowchart TD
    user[사용자]

    subgraph Client [Frontend - Browser]
        UI[React 19 SPA]
        MP[MediaPipe Vision]
        Three[Three.js Visual]
        Store[Zustand Store]
    end

    subgraph Server [Backend - EC2 Server]
        API[FastAPI Server]
        Auth[JWT Auth Service]
    end

    subgraph Data [Database]
        DB[(PostgreSQL)]
    end

    user -->|웹캠 스트림| MP
    MP -->|실시간 랜드마크 추출| UI
    MP -->|포즈 데이터| Three
    UI -->|시각 청각 피드백| user
    
    UI -->|API 요청 - Axios| API
    API -->|사용자 기록 관리| DB
    API -->|SSO - Google Kakao| Auth

    classDef person fill:#F3E8FF,stroke:#7C3AED,stroke-width:2px;
    classDef c_container fill:#E8F1FF,stroke:#2563EB,stroke-width:2px;
    classDef external fill:#FFF4E5,stroke:#F59E0B,stroke-width:2px;
    classDef datastore fill:#E9FBF0,stroke:#16A34A,stroke-width:2px;

    class user person;
    class UI,MP,Three,Store c_container;
    class API,Auth external;
    class DB datastore;

▲ MediaPipe 기반 클라이언트 AI 처리 및 백엔드 연동 구조

2. 주요 기능 (Key Features)

실시간 자세 분석

MediaPipe를 활용해 거북목(NTSD), 어깨 불균형(SLD) 등을 실시간으로 감지하고 경고합니다.

마이페이지 대시보드

누적된 자세 데이터를 시각화하여 사용자의 자세 습관 변화와 경고 이력을 제공합니다.

3. 실시간 AI 자세 분석 Flow

사용자의 웹캠 영상이 브라우저 내에서 분석되어 데이터베이스에 저장되기까지의 흐름입니다. 

sequenceDiagram
    participant U as user
    participant CAM as Webcam
    participant MP as MediaPipe (Browser)
    participant UI as React UI (Logic)
    participant API as FastAPI Server
    participant DB as PostgreSQL

    U->>UI: 1. 측정 시작 요청
    UI->>CAM: 2. 스트림 요청 (getUserMedia)
    CAM-->>UI: 3. Video Stream
    
    loop Real-time Analysis (Frame by Frame)
        UI->>MP: 4. 프레임 전달
        MP-->>UI: 5. 랜드마크(좌표) 반환
        UI->>UI: 6. 지표 계산 (NTSD, ETSD, SLD)
        
        opt 임계값 초과 (Bad Pose)
            UI-->>U: 7. 경고 알림 (Audio/Visual)
        end
    end

    U->>UI: 8. 측정 종료
    UI->>API: 9. 세션 데이터 전송 (POST /pose)
    API->>DB: 10. 자세 기록 저장
    DB-->>API: 11. 저장 완료
    API-->>UI: 12. 결과 리포트 생성

4. 데이터베이스 설계 (ERD)

사용자 정보와 시계열 포즈 데이터를 효율적으로 관리하기 위한 PostgreSQL 스키마입니다. 

erDiagram
    users ||--o{ pose : "has many"
    pose ||--o{ pose_detected : "has many"

    users {
        UUID id PK
        VARCHAR email UK
        VARCHAR name
        VARCHAR provider
        TIMESTAMPTZ created_at
    }

    pose {
        UUID id PK
        UUID user_id FK
        TIMESTAMPTZ created_at
        TIMESTAMPTZ ended_at
        JSONB measurement
    }

    pose_detected {
        UUID id PK
        UUID pose_id FK
        TIMESTAMPTZ occurred_at
        FLOAT duration_sec
        FLOAT avg_delta_ntsd
        FLOAT avg_delta_etsd
        FLOAT avg_delta_sld
        JSONB status
    }

▲ Users, Pose, PoseDetected 주요 엔티티 관계

5. 기술 스택 (Tech Stack)

Frontend & AI
React 19 TypeScript MediaPipe Three.js Zustand TailwindCSS
Backend
Python FastAPI PostgreSQL AsyncPG JWT
Management
Git GitHub

6. 트러블 슈팅

개발/배포 과정에서 발생한 이슈를 증상 → 원인 → 해결 흐름으로 정리했습니다.

  • 자세 인식 정확도 관련 트러블
    증상
    정상 자세임에도 경고 발생
    원인
    카메라 품질 문제로 인한 노이즈 발생
    해결
    EMA(지수 이동 평균) 스무딩으로 노이즈 감소
  • 서버 · 데이터 처리 트러블
    증상
    DB 부하 증가, 의미 없는 데이터 축적
    원인
    실시간 감지를 그대로 DB 저장
    해결
    의미 있는 이벤트(3초 이상 유지)만 저장
    JSONB 구조로 확장성 확보

Project Info