Skip to content

Architecture

Jump to bottom
EunHye (Grace) edited this page Oct 14, 2026 · 2 revisions

시스템 아키텍처

최초 작성: 2026-10-08 | 최종 업데이트: 2026-10-14
ADR-001(FE 배포), ADR-004(백엔드 기술 스택) 반영

전체 구조

graph TD
    subgraph Client
        WEB[React PWA<br/>Vite + TypeScript<br/>max-width 390px]
    end

    subgraph Vercel
        CDN[Vercel Edge<br/>정적 파일 서빙]
    end

    subgraph Server["서버 (배포 환경 미정)"]
        API[Spring Boot REST API<br/>:8080]
    end

    subgraph Storage
        DB[(MySQL)]
        S3[AWS S3<br/>미디어 파일]
    end

    subgraph External
        GOOGLE[Google OAuth 2.0]
        OPENAI[OpenAI API<br/>Whisper STT + GPT-4o]
    end

    WEB -->|HTTPS / JSON| API
    WEB -->|배포| CDN
    API -->|JPA| DB
    API -->|SDK v2| S3
    API -->|OAuth 토큰 검증| GOOGLE
    API -->|음성 전사 + 기록 초안| OPENAI
    WEB -->|Presigned URL 직접 업로드 가능| S3
Loading

레포 구조

PIC-2-team-project/
├── frontend/   ← React PWA (Vite + TypeScript)
└── backend/    ← Spring Boot

기술 스택

Frontend

항목 기술
프레임워크 React 19 + TypeScript 6
번들러 Vite 8
라우터 react-router-dom 7
테스트 Vitest + @testing-library/react
PWA vite-plugin-pwa
배포 Vercel (main 브랜치 push → 자동 배포)

Backend

항목 기술
프레임워크 Spring Boot 4.1.1 + Java 21
ORM Spring Data JPA + Hibernate
DB MySQL 8.x (프로덕션), H2 (개발)
인증 Spring Security 7 + jjwt 0.12.x
Refresh Token DB 테이블 (refresh_tokens)
OAuth spring-security-oauth2-client (Google)
파일 스토리지 AWS S3 (AWS SDK v2)
AI OpenAI Java SDK — Whisper STT + GPT-4o
API 문서 springdoc-openapi 3.1.0 (Swagger UI)
유틸 Lombok

결정 근거와 검토한 대안: ADR-001, ADR-004

로컬 포트

서비스 포트
FE (dev) 3000
BE 8080
DB 3306
Swagger UI http://localhost:8080/swagger-ui
OpenAPI JSON http://localhost:8080/api-docs

주요 흐름

인증 흐름

  1. 클라이언트 → POST /api/auth/login → access token (15분, Bearer) + refresh token (30일, HttpOnly cookie)
  2. 보호 API 요청: Authorization: Bearer {accessToken} 헤더
  3. 만료 시 POST /api/auth/refresh → 새 access token 발급

파일 업로드 흐름

  1. 클라이언트 → POST /api/care-recipients/{id}/media (서버 프록시 방식)
  2. 서버 → AWS S3 업로드 → mediaId 반환
  3. 다운로드: GET /api/.../media/{id}/download-url → 5분 유효 Presigned URL

AI 기록 초안 생성 흐름

  1. 클라이언트 → POST /api/ai/record-drafts (텍스트 또는 음성 mediaId)
  2. 서버 → Whisper STT (음성인 경우) → GPT-4o 카테고리 분류 + 초안 작성 → transcript, content, category 반환
  3. 클라이언트 → 수정 후 POST /api/care-recipients/{id}/records 로 저장

해소된 미결 사항

항목 결정 근거
FE 배포 환경 Vercel Hobby (MVP), 상업화 시 Vercel Pro 또는 Cloudflare Pages ADR-001
BE 배포 환경 미정 — 클라우드 배포 환경 선정 필요 —
인증 토큰 저장 방식 access token: Bearer 헤더, refresh token: HttpOnly Secure cookie + DB 테이블 ADR-004
파일 업로드 스토리지 AWS S3 (서버 프록시 업로드, Presigned URL 다운로드) ADR-004

Clone this wiki locally