# dawn-guys/showmoa-backend architecture

> Architecture diagram of the GitHub repository dawn-guys/showmoa-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dawn-guys/showmoa-backend
- Repository: https://github.com/dawn-guys/showmoa-backend

## Overview

ShowMoa is a Spring Boot backend for discovering performances and theatres, saving favorites, and managing an in-service calendar; ticket purchases remain with external ticketing sites. The main journey is performance search or map exploration, then detail viewing, wishlist management, and calendar retrieval. Separate capabilities include account/authentication, holiday lookup, and scheduled KOPIS ingestion. The graph follows documented product scope and sampled service relationships; some controller wiring and unsampled domain implementations are represented only where README documentation supports them.

Main entry points: [`src/main/java/com/dawnguys/findtheatre/FindTheatreApplication.java`](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/FindTheatreApplication.java) (ShowMoa API), [`src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java`](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java) (Theatre API), [`src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java`](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java) (Wishlist and calendar), [`src/main/java/com/dawnguys/findtheatre/user/UserService.java`](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/user/UserService.java) (User management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Performance discovery"]
  node_performance_api["Performance API"]
  node_performance_data[("Performance data<br/>[Performance.java]")]
  node_theatre_api["Theatre API"]
  node_theatre_data[("Theatre data<br/>[Theatre.java]")]
  node_map_services["Map search clients"]
end

subgraph group_personal["Personal planning"]
  node_wishlist_api["Wishlist and calendar"]
  node_wishlist_data[("Wishlist data<br/>[Wishlist.java]")]
  node_holiday_api["Holiday API"]
  node_holiday_client["Holiday client"]
end

subgraph group_identity["Accounts and access"]
  node_user_api["User management<br/>[UserService.java]"]
  node_user_data[("User accounts<br/>[User.java]")]
  node_auth_api["Authentication<br/>[AuthService.java]"]
  node_email_verification["Email verification"]
  node_oauth["OAuth login"]
end

subgraph group_ingestion["Data ingestion"]
  node_kopis_sync["KOPIS sync"]
  node_kopis_theatres["Theatre sync"]
  node_kopis_client["KOPIS client<br/>[KopisClient.java]"]
end

subgraph group_shared["Shared services"]
  node_common_errors["API error handling"]
end

node_visitor(("Frontend user"))
node_naver{{"Naver Map APIs"}}
node_holiday_service{{"Public holiday source"}}
node_kopis{{"KOPIS API"}}
node_backend["ShowMoa API"]

node_visitor -->|"uses API"| node_backend
node_backend -.->|"routes requests"| node_performance_api
node_backend -.->|"routes requests"| node_theatre_api
node_backend -.->|"routes requests"| node_wishlist_api
node_backend -.->|"routes requests"| node_user_api
node_performance_api -->|"queries"| node_performance_data
node_performance_api -->|"checks favorites"| node_wishlist_data
node_theatre_api -->|"queries"| node_theatre_data
node_theatre_api -->|"loads shows"| node_performance_data
node_theatre_api -->|"checks favorites"| node_wishlist_data
node_theatre_api -->|"geocodes and searches"| node_map_services
node_map_services -.->|"searches locations"| node_naver
node_wishlist_api -->|"loads shows"| node_performance_data
node_wishlist_api -->|"loads user"| node_user_data
node_wishlist_api -->|"saves and lists"| node_wishlist_data
node_holiday_api -->|"fetches holidays"| node_holiday_client
node_holiday_client -.->|"requests dates"| node_holiday_service
node_user_api -->|"manages accounts"| node_user_data
node_user_api -->|"checks verification"| node_email_verification
node_user_api -->|"logs out after changes"| node_auth_api
node_auth_api -->|"looks up account"| node_user_data
node_oauth -.->|"finds or creates account"| node_user_data
node_kopis_sync -->|"fetches performance data"| node_kopis_client
node_kopis_sync -->|"syncs facilities"| node_kopis_theatres
node_kopis_sync -->|"writes performances"| node_performance_data
node_kopis_theatres -->|"fetches facility details"| node_kopis_client
node_kopis_theatres -->|"saves facilities"| node_theatre_data
node_kopis_client -.->|"requests source data"| node_kopis
node_common_errors -.->|"formats errors"| node_backend

click node_performance_api "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/performance/PerformanceService.java"
click node_performance_data "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/performance/Performance.java"
click node_theatre_api "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java"
click node_theatre_data "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/theatre/Theatre.java"
click node_map_services "https://github.com/dawn-guys/showmoa-backend/tree/main/src/main/java/com/dawnguys/findtheatre/external/map"
click node_wishlist_api "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java"
click node_wishlist_data "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/wishlist/Wishlist.java"
click node_holiday_api "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/holiday/HolidayService.java"
click node_holiday_client "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/holiday/HolidayApiClient.java"
click node_user_api "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/user/UserService.java"
click node_user_data "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/user/User.java"
click node_auth_api "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/auth/AuthService.java"
click node_email_verification "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/auth/email/EmailVerificationService.java"
click node_oauth "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/auth/oauth/CustomOAuth2UserService.java"
click node_kopis_sync "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/kopis/KopisPerformanceSyncService.java"
click node_kopis_theatres "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/kopis/KopisTheatreSyncService.java"
click node_kopis_client "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/kopis/KopisClient.java"
click node_common_errors "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/common/exception/GlobalExceptionHandler.java"
click node_backend "https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/FindTheatreApplication.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_performance_api,node_performance_data,node_theatre_api,node_theatre_data,node_map_services,node_visitor toneBlue
class node_wishlist_api,node_wishlist_data,node_holiday_api,node_holiday_client toneAmber
class node_user_api,node_user_data,node_auth_api,node_email_verification,node_oauth,node_naver,node_kopis,node_backend toneMint
class node_kopis_sync,node_kopis_theatres,node_kopis_client toneRose
class node_common_errors,node_holiday_service toneIndigo
```

## Components

### Performance discovery

- [Performance API](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/performance/PerformanceService.java): `src/main/java/com/dawnguys/findtheatre/performance/PerformanceService.java`
- [Performance data](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/performance/Performance.java): `src/main/java/com/dawnguys/findtheatre/performance/Performance.java`
- [Theatre API](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java): `src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java`
- [Theatre data](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/theatre/Theatre.java): `src/main/java/com/dawnguys/findtheatre/theatre/Theatre.java`
- [Map search clients](https://github.com/dawn-guys/showmoa-backend/tree/main/src/main/java/com/dawnguys/findtheatre/external/map): `src/main/java/com/dawnguys/findtheatre/external/map`

### Personal planning

- [Wishlist and calendar](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java): `src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java`
- [Wishlist data](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/wishlist/Wishlist.java): `src/main/java/com/dawnguys/findtheatre/wishlist/Wishlist.java`
- [Holiday API](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/holiday/HolidayService.java): `src/main/java/com/dawnguys/findtheatre/holiday/HolidayService.java`
- [Holiday client](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/holiday/HolidayApiClient.java): `src/main/java/com/dawnguys/findtheatre/external/holiday/HolidayApiClient.java`

### Accounts and access

- [User management](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/user/UserService.java): `src/main/java/com/dawnguys/findtheatre/user/UserService.java`
- [User accounts](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/user/User.java): `src/main/java/com/dawnguys/findtheatre/user/User.java`
- [Authentication](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/auth/AuthService.java): `src/main/java/com/dawnguys/findtheatre/auth/AuthService.java`
- [Email verification](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/auth/email/EmailVerificationService.java): `src/main/java/com/dawnguys/findtheatre/auth/email/EmailVerificationService.java`
- [OAuth login](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/auth/oauth/CustomOAuth2UserService.java): `src/main/java/com/dawnguys/findtheatre/auth/oauth/CustomOAuth2UserService.java`

### Data ingestion

- [KOPIS sync](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/kopis/KopisPerformanceSyncService.java): `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisPerformanceSyncService.java`
- [Theatre sync](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/kopis/KopisTheatreSyncService.java): `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisTheatreSyncService.java`
- [KOPIS client](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/external/kopis/KopisClient.java): `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisClient.java`

### Shared services

- [API error handling](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/common/exception/GlobalExceptionHandler.java): `src/main/java/com/dawnguys/findtheatre/common/exception/GlobalExceptionHandler.java`

### Other components

- **Frontend user**
- **Naver Map APIs**
- **Public holiday source**
- **KOPIS API**
- [ShowMoa API](https://github.com/dawn-guys/showmoa-backend/blob/main/src/main/java/com/dawnguys/findtheatre/FindTheatreApplication.java): `src/main/java/com/dawnguys/findtheatre/FindTheatreApplication.java`

## Connections

- Frontend user → ShowMoa API: uses API (evidence: `README.md`)
- ShowMoa API → Performance API: routes requests
- ShowMoa API → Theatre API: routes requests
- ShowMoa API → Wishlist and calendar: routes requests
- ShowMoa API → User management: routes requests
- Performance API → Performance data: queries (evidence: `src/main/java/com/dawnguys/findtheatre/performance/PerformanceService.java`)
- Performance API → Wishlist data: checks favorites (evidence: `src/main/java/com/dawnguys/findtheatre/performance/PerformanceService.java`)
- Theatre API → Theatre data: queries (evidence: `src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java`)
- Theatre API → Performance data: loads shows (evidence: `src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java`)
- Theatre API → Wishlist data: checks favorites (evidence: `src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java`)
- Theatre API → Map search clients: geocodes and searches (evidence: `src/main/java/com/dawnguys/findtheatre/theatre/TheatreService.java`)
- Map search clients → Naver Map APIs: searches locations
- Wishlist and calendar → Performance data: loads shows (evidence: `src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java`)
- Wishlist and calendar → User accounts: loads user (evidence: `src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java`)
- Wishlist and calendar → Wishlist data: saves and lists (evidence: `src/main/java/com/dawnguys/findtheatre/wishlist/WishlistService.java`)
- Holiday API → Holiday client: fetches holidays (evidence: `src/main/java/com/dawnguys/findtheatre/holiday/HolidayService.java`)
- Holiday client → Public holiday source: requests dates
- User management → User accounts: manages accounts (evidence: `src/main/java/com/dawnguys/findtheatre/user/UserService.java`)
- User management → Email verification: checks verification (evidence: `src/main/java/com/dawnguys/findtheatre/user/UserService.java`)
- User management → Authentication: logs out after changes (evidence: `src/main/java/com/dawnguys/findtheatre/user/UserService.java`)
- Authentication → User accounts: looks up account (evidence: `src/main/java/com/dawnguys/findtheatre/auth/AuthService.java`)
- OAuth login → User accounts: finds or creates account (evidence: `src/main/java/com/dawnguys/findtheatre/auth/oauth/CustomOAuth2UserService.java`)
- KOPIS sync → KOPIS client: fetches performance data (evidence: `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisPerformanceSyncService.java`)
- KOPIS sync → Theatre sync: syncs facilities (evidence: `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisPerformanceSyncService.java`)
- KOPIS sync → Performance data: writes performances (evidence: `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisPerformanceSyncService.java`)
- Theatre sync → KOPIS client: fetches facility details (evidence: `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisTheatreSyncService.java`)
- Theatre sync → Theatre data: saves facilities (evidence: `src/main/java/com/dawnguys/findtheatre/external/kopis/KopisTheatreSyncService.java`)
- KOPIS client → KOPIS API: requests source data
- API error handling → ShowMoa API: formats errors