3 서비스 아키텍처 — 텍스트로 보기¶

← 다이어그램으로 · 그림의 라벨과 연결을 원본 draw.io 파일에서 그대로 뽑았습니다. 183항목 · 69연결.

FillMap · Application Architecture (SA v2 · 2026.07)

색상 = 화면 (헤더에서 선언 → 나가는 선 → 호출하는 API 행 테두리로 종결):
로그인·온보딩
① 지도 홈
② 격자 썸네일
③ 핫구역
④ 격자 상세
⑤ 신고 모달
⑥ 촬영·업로드
⑦ 개인 도감
설정·프로필
운영자 콘솔
스폰서 포털
③ 서비스 계약
사용자
운영자
스폰서 (광고주)

① 클라이언트¶

로그인·온보딩¶

카카오 로그인 (OIDC)
Apple·로컬 로그인 (미정)
위치·카메라 권한 요청
세션 유지 (Refresh)

① 지도 홈¶

내 격자 색칠 (뷰포트 폴링)
미점령 격자 미표시 정책
미션 레이어 (면·선·점·경계)
미션 칩 + 숫자 배지
미션 바텀시트 (3단)
행정동 검색·자동완성
게스트 열람 (지도·핫구역)

② 격자 썸네일¶

격자 요약 (점령·영상 수)
최근 업로드·누적 조회수
썸네일 그리드 (정렬 고정)
좋아요 · 취소

③ 핫구역¶

순위 리스트 (조회수 산정)
갱신 시각·카운트다운
항목 탭 → 격자 상세

④ 격자 상세¶

격자 표시명 (행정동)
행정 지역명·활동 지표
격자 내 영상 목록
영상 재생 (상태 분기)
영상 신고 진입

⑤ 신고 모달¶

신고 사유 선택
제출 → 접수 안내

⑥ 촬영·업로드¶

촬영 (격자 내 GPS 검증)
갤러리 선택 (1~30초)
업로드·인코딩 진행 표시
AI 하이라이트 구간 조정
AI 블러 확인·토글
공개 범위 선택
스탬프 획득 연출
영상 교체·삭제·공유

⑦ 개인 도감¶

요약 (격자·영상·뱃지·스트릭)
지도 뷰 (기존 API 재사용)
갤러리 뷰·정렬
뱃지 뷰·필터
지역별 탐험률 (동 단위)
스탬프북
공개범위 설정

설정·프로필¶

프로필 조회
닉네임·색상·이미지 수정
로그아웃
계정 삭제

운영자 콘솔 (Admin · Web)¶

신고 처리 → 블라인드
사용자 차단·Trust Score
통계 모니터링
미션 수동 등록

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

캠페인 관리
스폰서 격자 지정
성과 리포트 조회

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

② REST API¶

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}

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

④ Repository · 테이블¶

AuthService — SysA · Auth Service
UserService — SysA · Auth Service
GridQueryService — SysA · Grid Service
HotZoneService — SysA · Grid Service
MissionService — SysA · Mission Service
VideoService + 인코딩 워커 — SysA · Video Service
UserGridQueryService — SysA · Collection Service
RegionService — SysA · Region Service
SocialService — SysA · Social Service
ModerationService — SysA · Moderation Service
NotificationService — SysA · Notification Service

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

NotificationRepository¶

notifications
notification_opt_outs
push_tokens

AI 처리 환경 — 상시 Python FastAPI 서버 · EC2¶

(Lambda·GPU 대안 기각 · 1080p 다운스케일 필수 전제)

Kafka video.uploaded 컨슈머
1080p·30fps 다운스케일
FFmpeg 인코딩·썸네일
PySceneDetect 장면 분할
CLIP 하이라이트 스코어링
YOLO 얼굴·차번호 블러
pHash 중복 검사
산출: 인코딩본·썸네일 → S3 · videos.processing_status = READY · 하이라이트 구간 메타

⑤ 저장소 (Data Tier)¶

PostgreSQL + PostGIS
Redis (Hot ZSET·캐시)
S3 (원본·인코딩본)

연결¶

Kafka video.uploaded 컨슈머 → 1080p·30fps 다운스케일
1080p·30fps 다운스케일 → FFmpeg 인코딩·썸네일
FFmpeg 인코딩·썸네일 → PySceneDetect 장면 분할
PySceneDetect 장면 분할 → CLIP 하이라이트 스코어링
CLIP 하이라이트 스코어링 → YOLO 얼굴·차번호 블러
YOLO 얼굴·차번호 블러 → pHash 중복 검사
사용자 → ① 클라이언트
운영자 → 운영자 콘솔 (Admin · Web)
스폰서 (광고주) → 스폰서 포털 (광고주 · Web · P2)
로그인·온보딩 → Auth API
① 지도 홈 → Grid API
① 지도 홈 → Grid 확장 API
① 지도 홈 → Mission API
① 지도 홈 → Region API
② 격자 썸네일 → Grid API
② 격자 썸네일 → Grid 확장 API
② 격자 썸네일 → Video 재생 API
③ 핫구역 → Grid 확장 API
④ 격자 상세 → Grid API
④ 격자 상세 → Grid 확장 API
④ 격자 상세 → Video 재생 API
④ 격자 상세 → Region API
④ 격자 상세 → Social·Report API
⑤ 신고 모달 → Social·Report API
⑥ 촬영·업로드 → Video API
⑦ 개인 도감 → Collection API
⑦ 개인 도감 → Region API
⑦ 개인 도감 → User API
설정·프로필 → User API
설정·프로필 → Auth API
운영자 콘솔 (Admin · Web) → Social·Report API
운영자 콘솔 (Admin · Web) → Mission API
스폰서 포털 (광고주 · Web · P2) → Sponsor API — 미설계
Auth API → AuthService
User API → UserService
Grid API → GridQueryService
Grid 확장 API → HotZoneService
Grid 확장 API → VideoService + 인코딩 워커
Mission API → MissionService
Video 재생 API → VideoService + 인코딩 워커
Video API → VideoService + 인코딩 워커
Social·Report API → SocialService
Collection API → UserGridQueryService
Region API → RegionService
AuthService → UserRepository
UserService → UserRepository
GridQueryService → GridRepository
MissionService → MissionRepository
VideoService + 인코딩 워커 → VideoRepository
UserGridQueryService → CollectionRepository
UserGridQueryService → GridRepository
RegionService → RegionRepository
SocialService → FriendshipRepository
Social·Report API → ModerationService
ModerationService → FriendshipRepository
Notification API → NotificationService
NotificationService → NotificationRepository
UserRepository → PostgreSQL + PostGIS
GridRepository → PostgreSQL + PostGIS
VideoRepository → PostgreSQL + PostGIS
MissionRepository → PostgreSQL + PostGIS
RegionRepository → PostgreSQL + PostGIS
CollectionRepository → PostgreSQL + PostGIS
FriendshipRepository → PostgreSQL + PostGIS
HotZoneService → Redis (Hot ZSET·캐시)
VideoService + 인코딩 워커 → S3 (원본·인코딩본) — presigned·재생
VideoService + 인코딩 워커 → AI 처리 환경 — 상시 Python FastAPI 서버 · EC2 — Kafka video.uploaded
AI 처리 환경 — 상시 Python FastAPI 서버 · EC2 → S3 (원본·인코딩본) — 인코딩본·썸네일
AI 처리 환경 — 상시 Python FastAPI 서버 · EC2 → PostgreSQL + PostGIS — READY 갱신