KPOT

Where fandom becomes a journey ✨

Turn the places your favorite K-pop artists love into your next trip.

KPOT is a travel discovery service that maps K-pop artists to the real-world places they're connected to — the café an idol loves, the studio where a music video was filmed, the agency building fans line up in front of, the venue where a concert was held.

For global fans, being a fan and planning a trip to Korea are the same dream. KPOT turns that dream into a route: pick your favorite artists, explore their spots on the map, certify your visit on-site, earn XP, write a review, find travel companions and chat with them.

Built for the 2026 Korea Tourism Data Utilization Competition (관광데이터 활용 공모전), KPOT reimagines open tourism data (한국관광공사 TourAPI, 한국문화정보원 촬영지 데이터) through the lens of K-pop culture.

🇰🇷 한국어 요약 — KPOT은 K-pop 아티스트와 연관된 장소(스팟)를 지도에서 찾고, 현장에서 방문을 인증하고, 리뷰·커뮤니티·동행 채팅으로 팬들과 공유하는 서비스입니다. 주 사용자는 K-pop 성지순례를 위해 방한하는 일본어·영어·중국어권 관광객이며(UI 4개 언어), 한국관광공사 TourAPI와 공공데이터에 관리자 큐레이션·AI 발굴·팬 제보를 더해 스팟을 구축합니다.

Home — language-specific hero banners, popular artists, trending spots ranked by popularity score, live & upcoming events, your favorite artists, unified search

Map — Kakao Map with bounds-based loading, count bubbles when zoomed out (3 zoom tiers), event pins with a halo, 8 category filters, favorites-only toggle

Spot Detail — gallery with photo credits, rating breakdown, multilingual reviews, visit certification, related videos & photos, "open on map", data sources block

Mobile — a separate mobile component set for every screen · Home, Map, Spot Detail and Artist in English

Community — free board & companion recruitment with group chat

Artist — spots, related contents, favorite toggle, official fandom color as the app accent

  Pick your bias  →  Explore their spots  →  Go there  →  Certify on-site  →  Earn XP  →  Review & share  →  Find companions
   (onboarding)        (search · map)        (route)      (visit)            (level up)   (community)        (chat)

Amounts are farm-resistant by design: the highest reward is gated on admin acceptance, and the ledger is append-only. Level L needs 50·(L−1) + 10·(L−1)² cumulative XP.

Production, as of 2026-09-28:

Spots enter the system through five pipelines, all landing in the same Spot model with per-row provenance:

Artist ↔ Spot is many-to-many (ArtistSpot), so one café can belong to several idols and one artist can have dozens of spots.

Data principles we committed to (all recorded as ADRs in kpot-document/decisions/):

• Every imported photo stores its source, license and author and is credited on screen; photos whose origin can't be established are taken down (ADR 0006).
• Human-generated data — reviews, likes, bookmarks, comments, posts, companions — is never seeded with fake users on production (ADR 0007).
• User GPS never reaches the server (ADR 0008). Artist colors are only the ones officially announced by the agency (ADR 0009).
• Every pipeline run leaves a dated run log with per-row provenance in kpot-document/data/.

flowchart LR
    subgraph Clients
        FE["kpot-fe<br/>React 18 · Vite<br/>kpot.my"]
        ADMIN["kpot-admin<br/>React 18 · Ant Design · TanStack Query<br/>admin.kpot.my"]
    end

    subgraph AWS
        AMP["AWS Amplify<br/>(static hosting · CI on push to main)"]
        API["kpot-api<br/>Spring Boot 4.1 · Java 21<br/>Docker on EC2 · api.kpot.my"]
        DB[("MySQL<br/>Flyway migrations")]
        S3["S3 + CDN<br/>cdn.kpot.my"]
    end

    TOUR["TourAPI<br/>(한국관광공사)"]
    KAKAO["Kakao Map SDK"]
    OAUTH["Kakao · Google OAuth"]
    GA["Google Analytics"]

    FE --> AMP
    ADMIN --> AMP
    FE -- "REST /api/v1 · JWT" --> API
    FE -- "WebSocket / STOMP (chat)" --> API
    ADMIN -- "REST /api/v1 · JWT (AUTH_ADMIN)" --> API
    API --> DB
    API --> S3
    API -- "nightly sync" --> TOUR
    FE --> KAKAO
    FE --> OAUTH
    FE --> GA
    API --> OAUTH

• Auth — JWT access token (1h, stateless) + refresh token (14d, persisted & rotated). Roles: AUTH_USER, AUTH_ADMIN.
• API — /api/v1/*, ~190 endpoints in 45 controllers across 20 domains (artist, artistspot, spot, review, visit, bookmark, post, companion, chat, interaction, notification, gamification, popularity, ingestion, tourapi, inquiry, member, auth, admin, stats). OpenAPI via springdoc.
• Realtime — Spring WebSocket + STOMP with 10 s heart-beats so idle sockets survive the proxy. Single instance today; a Redis relay is the planned scale-out path (ADR 0002).
• Schema — Flyway-managed (V22 and counting); Hibernate runs in validate mode so entities never drift from migrations.
• Nightly jobs (KST) — 04:00 popularity decay · 04:30 orphaned-image sweep · 05:00 expired-token cleanup · 05:30 notification cleanup · 06:00 TourAPI sync.
• Delivery — Frontend & admin deploy from main via AWS Amplify (production and dev are separate Amplify apps in separate AWS accounts; the build fails if VITE_API_URL is unset so the two can never cross). API deploys via GitHub Actions → SSH → docker compose up --build on EC2, dev branch to the dev server and main to production.
• Images — uploaded to S3 inside the write transaction and served from cdn.kpot.my, each with a stored credit.

Frontend (kpot-fe)

• React 18 + Vite 5, React Router v7 (createBrowserRouter), ResponsiveRoute that renders a desktop or mobile component by viewport width
• CSS Modules with CSS-variable design tokens (color, typography, spacing, radius, shadow) extracted directly from Figma — no Tailwind, no CSS-in-JS. The accent token is swapped at runtime to the favorite artist's official color
• Pretendard Variable typeface, lottie-react animations, @stomp/stompjs for chat
• Custom i18n layer (KO / JA / EN / ZH) — static UI strings from dictionaries, dynamic content translated server-side
• No global state library by design; one language context plus local state and custom hooks
• Map clustering computed from a server grid endpoint; on-device geolocation for visit checks and the report map picker
• Playwright end-to-end suites per domain (account, community, chat, inquiry, notification, settings, social, mobile), i18n key checks, a no-mock-data check and a whole-app design QA walk
• SEO — per-route <head>, robots.txt and sitemap generated after build; Google Analytics on production only

Backend (kpot-api)

• Java 21 · Spring Boot 4.1 · Spring Security (JWT) · Spring Data JPA · Spring WebSocket · Lombok
• Layering: Controller (HTTP + @Secured) → Service (@Transactional) → Repository; infrastructure behind interfaces (FileManager ← S3FileManager)
• Polymorphic Like / Comment / Report shared across reviews, posts, companions, spots and chat messages
• Soft delete via LogicalDeleteEntity, @EntityGraph against N+1, Caffeine caches for hot reads
• Domain events wire modules together (companion created → chat room, member withdrawn → rooms updated, level-up → notification)
• Profiles: local / dev / prod, secrets only via environment variables; Gradle tests run in CI before every deploy
• Domain docs per module (docs/domain/*.md) plus a build roadmap

Admin (kpot-admin)

• Ant Design 5 tables/forms/drawers themed with the brand red, TanStack Query 5 for server state with per-mutation invalidation and live sidebar badges
• Kakao Map coordinate picker, image manager (append / delete / reorder / credit editing), bulk artist linking, multi-artist related contents, translation panel, data-quality audit view, test-account creation
• Playwright route walk that must pass before a change is called done

Infrastructure

• AWS Amplify (web + admin) · EC2 + Docker (API) · MySQL · S3 + CDN · GitHub Actions
• Domains: kpot.my · api.kpot.my · admin.kpot.my · cdn.kpot.my

• Docs first, single source of truth — kpot-document/TODO.md holds every open item across backend and frontend. Each item carries a Verify: command; we trust code > docs > memory.
• Backend changes ship with frontend instructions — any change to an endpoint or payload lands in TODO.md as an FE-actionable item in the same round.
• Figma-driven — every screen maps to a Figma node; tokens are extracted, not eyeballed.
• Verify before "done" — a task is complete when it's deployed and the Playwright sweep passes.
• ADRs for the big calls — deferring Next.js / responsive refactor, chat on MVC + STOMP, public-data import rules, AI-assisted discovery, popularity scoring, image credits, no fake UGC, no user location on the server, official artist colors only.
• Data work is evidence — every pipeline run writes a dated run log with per-row provenance; registries are committed so re-runs never duplicate.
• Branching — feature/* → dev → main; main is deploy-only. Conventional Commits everywhere.

KPOT is built on a Figma-driven design system. Every screen maps to a Figma node, and all visual values flow from a shared token file — keeping the product pixel-consistent and easy to scale.

A warm signature red (#F74C4C) sets the tone: energetic, friendly, and unmistakably K-pop. Once you pick a favorite artist, their official fandom color takes over the accent — the app dresses in your bias's colors.