3 서비스 아키텍처SERVICE ARCHITECTURE

① 클라이언트

② REST API

③ 서비스 계약

④ Repository · 테이블

⑤ 저장소 (Data Tier)

FillMap · Application Architecture (SA v2 · 2026.07)

색상 = 화면 (헤더에서 선언 → 나가는 선 → 호출하는 API 행 테두리로 종결):

로그인·온보딩

① 지도 홈

② 격자 썸네일

③ 핫구역

④ 격자 상세

⑤ 신고 모달

⑥ 촬영·업로드

⑦ 개인 도감

설정·프로필

운영자 콘솔

스폰서 포털

API 카드 헤더 연초록 = 종류 표시 · 서비스·Repository·저장소 연결 = 무채색 · AI 처리 환경 = 남색 강조 · ③ 각 칸의 작은 글씨 = 대응하는 SysA v2 서비스 (9종 1:1) · 경로는 전부 /api 접두사 (버전 미도입)

사용자

운영자

스폰서 (광고주)

로그인·온보딩

카카오 로그인 (OIDC)

Apple·로컬 로그인 (미정)

위치·카메라 권한 요청

세션 유지 (Refresh)

① 지도 홈

내 격자 색칠 (뷰포트 폴링)

미점령 격자 미표시 정책

미션 레이어 (면·선·점·경계)

미션 칩 + 숫자 배지

미션 바텀시트 (3단)

행정동 검색·자동완성

게스트 열람 (지도·핫구역)

② 격자 썸네일

격자 요약 (점령·영상 수)

최근 업로드·누적 조회수

썸네일 그리드 (정렬 고정)

좋아요 · 취소

③ 핫구역

순위 리스트 (조회수 산정)

갱신 시각·카운트다운

항목 탭 → 격자 상세

④ 격자 상세

격자 표시명 (행정동)

행정 지역명·활동 지표

격자 내 영상 목록

영상 재생 (상태 분기)

영상 신고 진입

⑤ 신고 모달

신고 사유 선택

제출 → 접수 안내

⑥ 촬영·업로드

촬영 (격자 내 GPS 검증)

갤러리 선택 (1~30초)

업로드·인코딩 진행 표시

AI 하이라이트 구간 조정

AI 블러 확인·토글

공개 범위 선택

스탬프 획득 연출

영상 교체·삭제·공유

⑦ 개인 도감

요약 (격자·영상·뱃지·스트릭)

지도 뷰 (기존 API 재사용)

갤러리 뷰·정렬

뱃지 뷰·필터

지역별 탐험률 (동 단위)

스탬프북

공개범위 설정

설정·프로필

프로필 조회

닉네임·색상·이미지 수정

로그아웃

계정 삭제

운영자 콘솔 (Admin · Web)

신고 처리 → 블라인드

사용자 차단·Trust Score

통계 모니터링

미션 수동 등록

스폰서 포털 (광고주 · Web · P2)

캠페인 관리

스폰서 격자 지정

성과 리포트 조회

Auth API

POST /api/auth/signup · login

POST /api/auth/logout

POST /api/auth/oauth/{provider}

POST /api/auth/reissue

Grid API

GET /api/grids (뷰포트)

GET /api/grids/{gridId}

Grid 확장 API

GET /api/grids/{id}/videos

GET /api/grids/hot

POST·DEL /api/videos/{id}/likes

Mission API

GET /api/missions/active

(bbox 없음 · TTL 1h 캐시)

Video 재생 API

GET /api/videos/{videoId}

(presigned GET · 상태 분기)

Social·Report API

POST /api/reports

POST /api/friends/requests (P2)

PATCH /api/friends/requests (P2)

GET·DELETE /api/friends (P2)

POST /api/friends/{id}/block (P2)

Video API

POST /api/videos/presigned-url

POST /api/videos (점령)

PUT /api/videos/{videoId}

PATCH /api/videos/{id}/visibility

DELETE /api/videos/{videoId}

Collection API

GET /api/collections/summary

GET /api/collections/grids

GET /api/collections/videos?regionCode

GET /api/collections/badges

Region API

GET /api/regions/search

GET /api/regions/stats

GET /api/regions/stats/by-point·by-grid

GET /api/regions/{code}

User API

GET /api/users/me

PATCH /api/users/me

DELETE /api/users/me

Notification API

POST·DELETE /api/notifications/tokens

GET /api/notifications/preferences

PATCH …/preferences/{category}

NotificationRepository

notifications

notification_opt_outs

push_tokens

Sponsor API

(미설계 — P2 캠페인·리포트)

AuthService

UserService

GridQueryService

HotZoneService

MissionService

VideoService + 인코딩 워커

UserGridQueryService

RegionService

SocialService

ModerationService

NotificationService

UserRepository

users

GridRepository

grids

user_grids

VideoRepository

videos

likes

MissionRepository

missions

mission_grids

user_missions

RegionRepository

regions

region_stats

CollectionRepository

badges

user_badges

streaks

FriendshipRepository

friendships

reports

PostgreSQL + PostGIS

Redis (Hot ZSET·캐시)

S3 (원본·인코딩본)

AI 처리 환경 — 상시 Python FastAPI 서버 · EC2
(Lambda·GPU 대안 기각 · 1080p 다운스케일 필수 전제)

Kafka video.uploaded 컨슈머

1080p·30fps 다운스케일

FFmpeg 인코딩·썸네일

PySceneDetect 장면 분할

CLIP 하이라이트 스코어링

YOLO 얼굴·차번호 블러

pHash 중복 검사

산출: 인코딩본·썸네일 → S3 · videos.processing_status = READY · 하이라이트 구간 메타

미설계

presigned·재생

Kafka video.uploaded

인코딩본·썸네일

READY 갱신