Architecture - PIC-2-team/PIC-2-team-project GitHub Wiki

μ‹œμŠ€ν…œ μ•„ν‚€ν…μ²˜

졜초 μž‘μ„±: 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
⚠️ **GitHub.com Fallback** ⚠️