# ssavice/be architecture

> Architecture diagram of the GitHub repository ssavice/be, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ssavice/be
- Repository: https://github.com/ssavice/be

## Overview

1. **Overall shape**
This is a single Spring Boot backend application (`SsaviceApplication`) organized as a modular monolith. The code is split by business domain rather than by technical layer, and most domains follow the same internal structure: HTTP controller → application service → repository/entity → external adapter if needed.

2. **Core domain modules**
The main business modules are `user`, `account`, `auth`, `company`, `book`, `serviceItem`, `review`, `wish`, `payment`, `imageResource`, `chatmember`, `address`, `region`, and `refund`. Each module owns its own entities, request/response DTOs, service classes, and persistence repositories, which makes the domain boundaries fairly explicit for diagramming.

3. **Typical request flow**
Most synchronous flows start in a controller, map into a command/model DTO, and then pass through a read/write service split. Many modules expose separate `ReadService`, `WriteService`, and facade-style `Service` classes, indicating a deliberate separation between query logic and mutation logic.

4. **Persistence boundary**
The application uses JPA/Hibernate for persistence, with repositories under each module’s `infrastructure/repository`. There is a shared `BaseEntity`, shared SQL schema/data bootstrap files, and some custom repository implementations where query complexity requires it, such as `book` and `serviceItem`. The `global/config/JpaConfig` and `QueryDSLConfig` suggest a mix of standard JPA and QueryDSL-based querying.

5. **Authentication and authorization**
Auth is centralized in the `auth` package and reinforced by global infrastructure. The app has a JWT filter, authentication and authorization interceptors, custom argument resolvers for injecting the current auth/refresh token, and custom annotations such as `@PermitAll`, `@RequireRole`, and `@CurrentAuth`. This means security is enforced both at the HTTP filter layer and inside controller method handling.

6. **User/account/company onboarding**
`user`, `account`, and `company` form the identity and seller/business onboarding area. `company` is more complex than a simple CRUD module: it includes business verification flow, a signup verification token, and an adapter/client for an external business-number validation service. `account` appears to manage provider-linked accounts, while `user` holds the core application user profile.

7. **External service integrations**
Several domains delegate to external platforms through adapter/client packages:
- `oauth` integrates with Kakao for social login.
- `company` integrates with an NTS-based verification API.
- `payment` integrates with Toss for payment confirm/cancel.
- `serviceItem` integrates with OpenSearch for search.
- `s3` abstracts AWS S3 for image/object storage.
These adapters are isolated behind client/service interfaces, which keeps vendor-specific DTOs out of the core domains.

8. **Eventing and async processing**
The architecture includes multiple asynchronous/event-driven paths. Kafka is present via `KafkaProducer`, event handlers, and config. There is also an outbox pattern: domain events are stored as `OutboxEvent`, processed by an `OutboxScheduler`, and then published outward. SQS is used for thumbnail-related messaging, with event DTOs and a consumer/listener pipeline. This suggests the system uses async messaging for side effects, retries, and decoupling.

9. **Media and image pipeline**
`imageResource` and `s3` together implement the file/media pipeline. Image metadata is stored in the database, while the binary object is handled through S3. S3 events and object-key generation are separated from image domain logic, and there are explicit validation/error cases for content type and size. This is likely a two-step flow: metadata lifecycle in DB, object lifecycle in storage.

10. **Commerce-like transaction flows**
`payment`, `refund`, `wish`, `review`, and `book` indicate the product supports transactional marketplace behavior. Payments are confirmed/canceled through Toss, refunds are represented explicitly, and reviews/wishes are separate user-generated domain modules. `book` and `serviceItem` likely represent inventory/listing-style objects, with search/filtering support on `serviceItem`.

11. **Shared infrastructure and cross-cutting concerns**
The `global` package contains shared exception handling, properties, constants, DTOs, utilities, and infrastructure config. It also includes OpenSearch, Kafka, S3, ShedLock, Swagger, and web MVC configuration. That indicates the repo is not just a domain model but a production-oriented backend with scheduled jobs, API docs, distributed locks, and standardized error handling.

12. **Runtime/deployment and verification**
The repository is built with Gradle and packaged for Docker; it also includes GitHub Actions workflows for CI and deployment, plus `docker-compose.yml` for local orchestration. Test coverage is broad across domain services, repositories, integration flows, and infrastructure adapters, which suggests the system’s architecture is intended to be validated at multiple boundaries rather than only through unit tests.

Main entry points: [`src/main/java/teamssavice/ssavice/SsaviceApplication.java`](https://github.com/ssavice/be/blob/develop/src/main/java/teamssavice/ssavice/SsaviceApplication.java) (Ssavice app), [`src/main/java/teamssavice/ssavice/serviceItem`](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/serviceItem) (Service items), [`src/main/java/teamssavice/ssavice/company`](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/company) (Company), [`src/main/java/teamssavice/ssavice/outbox`](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/outbox) (Outbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_app_main(("Ssavice app<br/>boot entrypoint"))
end

subgraph group_core["Core domains"]
  node_user_dom["Users<br/>identity domain"]
  node_account_dom["Accounts"]
  node_company_dom["Company<br/>seller onboarding"]
  node_book_dom["Books<br/>listing domain"]
  node_service_item_dom["Service items<br/>searchable listing"]
  node_payment_dom["Payments<br/>payment flow"]
  node_refund_dom["Refunds<br/>refund domain"]
  node_review_dom["Reviews<br/>user content"]
  node_wish_dom["Wishes<br/>user bookmarking"]
  node_image_dom["Images<br/>media metadata"]
  node_chat_dom["Chat members"]
  node_region_dom["Regions<br/>lookup data"]
end

subgraph group_integrations["Integrations"]
  node_oauth_kakao["Kakao OAuth<br/>social login"]
  node_company_nts["NTS verify<br/>external verification"]
  node_payment_toss["Toss payments<br/>payment gateway"]
  node_search_os["OpenSearch<br/>search backend"]
  node_storage_s3["S3 storage<br/>object storage"]
end

subgraph group_platform["Platform"]
  node_global_web["Web core<br/>shared web"]
  node_global_data["Data config<br/>shared persistence"]
  node_auth_dom["Auth<br/>token security"]
end

subgraph group_async["Async flows"]
  node_messaging["Kafka<br/>messaging bus"]
  node_outbox["Outbox<br/>event relay"]
  node_sqs_thumb["Thumbnail SQS<br/>async processing"]
end

node_app_main -->|"bootstraps"| node_global_web
node_app_main -->|"bootstraps"| node_global_data
node_app_main -->|"loads"| node_user_dom
node_app_main -->|"loads"| node_company_dom
node_app_main -->|"loads"| node_service_item_dom
node_user_dom -->|"uses"| node_auth_dom
node_account_dom -->|"uses"| node_auth_dom
node_company_dom -->|"verifies"| node_company_nts
node_auth_dom -->|"social login"| node_oauth_kakao
node_service_item_dom -->|"indexes/searches"| node_search_os
node_payment_dom -->|"confirms/cancels"| node_payment_toss
node_image_dom -->|"stores objects"| node_storage_s3
node_service_item_dom -.->|"attaches media"| node_image_dom
node_review_dom -.->|"references"| node_user_dom
node_wish_dom -.->|"references"| node_user_dom
node_book_dom -.->|"references"| node_company_dom
node_book_dom -.->|"filters by"| node_region_dom
node_service_item_dom -.->|"filters by"| node_region_dom
node_global_web -.->|"hooks"| node_messaging
node_company_dom -->|"publishes"| node_outbox
node_payment_dom -.->|"publishes"| node_outbox
node_outbox -->|"dispatches"| node_messaging
node_outbox -->|"dispatches"| node_sqs_thumb
node_sqs_thumb -->|"consumes"| node_storage_s3
node_global_data -.->|"supports"| node_book_dom
node_global_data -.->|"supports"| node_service_item_dom

click node_app_main "https://github.com/ssavice/be/blob/develop/src/main/java/teamssavice/ssavice/SsaviceApplication.java"
click node_global_web "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/global"
click node_global_data "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/global/config"
click node_user_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/user"
click node_account_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/account"
click node_auth_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/auth"
click node_company_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/company"
click node_book_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/book"
click node_service_item_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/serviceItem"
click node_payment_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/payment"
click node_refund_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/refund"
click node_review_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/review"
click node_wish_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/wish"
click node_image_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/imageresource"
click node_chat_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/chatmember"
click node_region_dom "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/region"
click node_oauth_kakao "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/oauth/infrastructure/kakao"
click node_company_nts "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/company/infrastructure/nts"
click node_payment_toss "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/payment/infrastructure/toss"
click node_search_os "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/serviceItem/infrastructure/opensearch"
click node_storage_s3 "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/s3"
click node_messaging "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/kafka"
click node_outbox "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/outbox"
click node_sqs_thumb "https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/sqs"

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_app_main toneBlue
class node_user_dom,node_account_dom,node_company_dom,node_book_dom,node_service_item_dom,node_payment_dom,node_refund_dom,node_review_dom,node_wish_dom,node_image_dom,node_chat_dom,node_region_dom toneAmber
class node_oauth_kakao,node_company_nts,node_payment_toss,node_search_os,node_storage_s3 toneMint
class node_global_web,node_global_data,node_auth_dom toneRose
class node_messaging,node_outbox,node_sqs_thumb toneIndigo
```

## Components

### Application

Spring Boot entrypoint and core runtime

- [Ssavice app](https://github.com/ssavice/be/blob/develop/src/main/java/teamssavice/ssavice/SsaviceApplication.java): boot entrypoint · Main Spring Boot application bootstrap · `src/main/java/teamssavice/ssavice/SsaviceApplication.java`

### Core domains

Primary business modules and their service/repository boundaries

- [Users](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/user): identity domain · User profile management with controller, service split, and JPA repository · `src/main/java/teamssavice/ssavice/user`
- [Accounts](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/account): linked accounts · Provider-linked account records and account services · `src/main/java/teamssavice/ssavice/account`
- [Company](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/company): seller onboarding · Business onboarding, verification flow, signup token, and persistence · `src/main/java/teamssavice/ssavice/company`
- [Books](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/book): listing domain · Book listing module with custom repository queries · `src/main/java/teamssavice/ssavice/book`
- [Service items](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/serviceItem): searchable listing · Service listing module with OpenSearch-backed search and custom queries · `src/main/java/teamssavice/ssavice/serviceItem`
- [Payments](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/payment): payment flow · Payment confirmation, cancellation, and persistence around Toss integration · `src/main/java/teamssavice/ssavice/payment`
- [Refunds](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/refund): refund domain · Refund information and refund service handling · `src/main/java/teamssavice/ssavice/refund`
- [Reviews](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/review): user content · Review creation and retrieval module · `src/main/java/teamssavice/ssavice/review`
- [Wishes](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/wish): user bookmarking · Wish list and bookmarking module · `src/main/java/teamssavice/ssavice/wish`
- [Images](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/imageresource): media metadata · Image resource lifecycle and metadata persistence · `src/main/java/teamssavice/ssavice/imageresource`
- [Chat members](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/chatmember): chat membership · Chat room membership persistence and service layer · `src/main/java/teamssavice/ssavice/chatmember`
- [Regions](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/region): lookup data · Regional reference data and read service · `src/main/java/teamssavice/ssavice/region`

### Integrations

External vendors and adapters

- [Kakao OAuth](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/oauth/infrastructure/kakao): social login · Kakao login adapter and API client · `src/main/java/teamssavice/ssavice/oauth/infrastructure/kakao`
- [NTS verify](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/company/infrastructure/nts): external verification · Business-number verification adapter and client · `src/main/java/teamssavice/ssavice/company/infrastructure/nts`
- [Toss payments](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/payment/infrastructure/toss): payment gateway · Toss confirm/cancel adapter and Feign client · `src/main/java/teamssavice/ssavice/payment/infrastructure/toss`
- [OpenSearch](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/serviceItem/infrastructure/opensearch): search backend · OpenSearch client and search document mapping for service items · `src/main/java/teamssavice/ssavice/serviceItem/infrastructure/opensearch`
- [S3 storage](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/s3): object storage · S3 service, key generation, and object/event handling · `src/main/java/teamssavice/ssavice/s3`

### Platform

Cross-cutting infrastructure and shared concerns

- [Web core](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/global): shared web · Filters, interceptors, resolvers, annotations, MVC config, and exception handling · `src/main/java/teamssavice/ssavice/global`
- [Data config](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/global/config): shared persistence · JPA, QueryDSL, and storage-related configuration plus base entity support · `src/main/java/teamssavice/ssavice/global/config`
- [Auth](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/auth): token security · JWT token issuance, refresh tokens, and authentication responses · `src/main/java/teamssavice/ssavice/auth`

### Async flows

Eventing, outbox, and background processing

- [Kafka](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/kafka): messaging bus · Kafka producer, event model, and handler layer · `src/main/java/teamssavice/ssavice/kafka`
- [Outbox](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/outbox): event relay · Outbox event persistence, scheduler, and publisher bridge · `src/main/java/teamssavice/ssavice/outbox`
- [Thumbnail SQS](https://github.com/ssavice/be/tree/develop/src/main/java/teamssavice/ssavice/sqs): async processing · Thumbnail event listener and SQS consumer pipeline · `src/main/java/teamssavice/ssavice/sqs`

## Connections

- Ssavice app → Web core: bootstraps · Registers shared web/security infrastructure
- Ssavice app → Data config: bootstraps · Enables persistence and query configuration
- Ssavice app → Users: loads · Starts user domain components
- Ssavice app → Company: loads · Starts company onboarding components
- Ssavice app → Service items: loads · Starts listing/search components
- Users → Auth: uses · User-facing requests rely on token auth
- Accounts → Auth: uses · Provider-linked account flows depend on tokens
- Company → NTS verify: verifies · Delegates business-number validation externally
- Auth → Kakao OAuth: social login · Supports Kakao OAuth sign-in
- Service items → OpenSearch: indexes/searches · Uses OpenSearch for search and filtering
- Payments → Toss payments: confirms/cancels · Delegates payment gateway operations
- Images → S3 storage: stores objects · Persists image binaries in object storage
- Service items → Images: attaches media · Service listings can reference image resources
- Reviews → Users: references · Reviews are authored by users
- Wishes → Users: references · Wish records belong to users
- Books → Company: references · Book listings relate to sellers/companies
- Books → Regions: filters by · Regional lookup supports book querying
- Service items → Regions: filters by · Regional lookup supports service item discovery
- Web core → Kafka: hooks · HTTP layer cooperates with async eventing
- Company → Outbox: publishes · Stores domain events for reliable relay
- Payments → Outbox: publishes · Payment changes may be relayed through outbox
- Outbox → Kafka: dispatches · Relays persisted events to Kafka
- Outbox → Thumbnail SQS: dispatches · Can forward events into thumbnail processing
- Thumbnail SQS → S3 storage: consumes · Thumbnail pipeline interacts with stored objects
- Data config → Books: supports · Shared JPA/QueryDSL configuration backs repositories
- Data config → Service items: supports · Shared JPA/QueryDSL configuration backs repositories
