# 023-dev/biram architecture

> Architecture diagram of the GitHub repository 023-dev/biram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/023-dev/biram
- Repository: https://github.com/023-dev/biram

## Overview

##### Project Type and Purpose
- This is a single-deploy Spring Boot application (monolithic server-side system) structured as a modular, hexagonal (ports-and-adapters) architecture.
- It exposes REST endpoints and WebSocket channels for features around auctions, bidding, chat, notifications, user management, daily activities, images, reviews and wishes.
- It integrates with relational storage via JPA, Redis caching, AWS S3 for media, OAuth2 providers (Kakao/Naver), JWT security, and a message broker for asynchronous notifications and bid events.

##### High-Level Components
- Clients: Browser or mobile apps
- HTTP(S) REST clients
- WebSocket clients (chat/notification channels)
- Spring Boot Application (“biram-service”):
- UI Layer: @RestController and WebSocket controllers per module
- Application Layer: port interfaces + service implementations per module
- Domain Layer: core entities, value objects, business rules
- Infrastructure Layer: adapters for JPA repositories, Redis caches, message brokers, S3 manager, OAuth2, JWT filters
- Global Config: security, Web MVC, WebSocket, Swagger, Redis, QueryDSL, S3, AWS, auditing
- Exception Handling: centralized @ControllerAdvice and custom exceptions
- Scheduling: auction expiration scheduler
- External Systems:
- RDBMS (e.g., MySQL/PostgreSQL)
- Redis cluster (caching, token store, auction/bid caches)
- AWS S3 bucket (image storage)
- OAuth2 Identity Providers (Kakao, Naver)
- Message broker (e.g., RabbitMQ/Kafka) for notifications and bid‐publish
- CI/CD pipeline (GitHub Actions + Docker + docker-compose)

##### Relationships and Data Flows
- Clients → HTTP Controllers → Application Services → Domain → Repositories (JPA) → RDBMS
- Clients → WebSocket Controllers → Application Services → Domain → Message Broker / In-memory session manager
- Application Services ↔ Redis Adapter for caching auction/bid/wish data
- Image upload requests → S3Service → AWS S3
- OAuth2 login flow → OAuth2TokenLoginFilter → OAuth2 providers → JwtTokenizer → Clients
- Auction expiration → Scheduled task → AuctionExpiredService → Message Broker → AuctionExpirationListener

##### Architectural Patterns & Principles
- Hexagonal (Ports & Adapters): each module defines input/output ports and has adapters in infrastructure.
- Layered: UI → Application → Domain → Infrastructure
- Module-per-Bounded-Context: auction, bid, chat, member, notification, review, wish, daily, image
- Infrastructure-agnostic domain; use DI to inject ports.
- Centralized cross-cutting concerns: security, exception handling, swagger, auditing.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    Clients["Clients (Browser/Mobile)"]:::external
    RDBMS[(RDBMS)]:::external
    RedisCache[(Redis Cache)]:::external
    S3Bucket[(AWS S3 Bucket)]:::external
    OAuth2Prov["OAuth2 Providers (Kakao/Naver)"]:::external
    MsgBroker[(Message Broker)]:::external

    %% Monolith Container
    subgraph "biram-service"
        direction TB

        subgraph "UI Layer" 
            direction TB
            AuctionController["AuctionController"]:::ui
            BidController["BidController"]:::ui
            ChatController["ChatController"]:::ui
            MemberController["MemberController"]:::ui
            NotificationController["NotificationController"]:::ui
            DailyActivityController["DailyActivityController"]:::ui
            ImageTestController["ImageTestController"]:::ui
            WishController["WishController"]:::ui
            AuthController["AuthController"]:::ui
            ChatWebSocketController["ChatWebSocketController"]:::ui
            NotificationMessageListener["NotificationMessageListener"]:::ui
        end

        subgraph "Application Layer"
            direction TB
            AuctionServiceImpl["AuctionCommandServiceImpl / AuctionQueryServiceImpl"]:::app
            BidServiceImpl["BidServiceImpl"]:::app
            ChatServiceImpl["ChatMessageServiceImpl / ChatRoomServiceImpl"]:::app
            DailyActivityServiceImpl["DailyActivityServiceImpl"]:::app
            ImageServiceImpl["ImageServiceImpl"]:::app
            MemberServiceImpl["MemberServiceImpl / PointServiceImpl"]:::app
            NotificationServiceImpl["NotificationServiceImpl"]:::app
            WishServiceImpl["WishServiceImpl"]:::app
            RefreshTokenServiceImpl["RefreshTokenServiceImpl"]:::app
        end

        subgraph "Domain Layer"
            direction TB
            DomainEntities["Entities & Value Objects"]:::domain
        end

        subgraph "Infrastructure Layer"
            direction TB
            JPAAdapters["JPA Repository Adapters"]:::infra
            RedisAdapters["Redis Cache Adapters"]:::infra
            S3Manager["AmazonS3Manager"]:::infra
            OAuth2JWT["OAuth2TokenLoginFilter / JwtTokenizer"]:::infra
            MsgAdapters["Message Broker Adapters"]:::infra
            Scheduler["AuctionSchedulerImpl"]:::infra
        end
    end

    %% Relationships
    Clients -->|"HTTP/REST"| AuctionController
    Clients -->|"HTTP/REST"| BidController
    Clients -->|"HTTP/REST"| ChatController
    Clients -->|"HTTP/REST"| MemberController
    Clients -->|"HTTP/REST"| NotificationController
    Clients -->|"HTTP/REST"| DailyActivityController
    Clients -->|"HTTP/REST"| ImageTestController
    Clients -->|"HTTP/REST"| WishController
    Clients -->|"HTTP/REST"| AuthController
    Clients -->|"WS"| ChatWebSocketController
    Clients -->|"WS"| NotificationMessageListener

    AuctionController -->|calls| AuctionServiceImpl
    BidController -->|calls| BidServiceImpl
    ChatController -->|calls| ChatServiceImpl
    MemberController -->|calls| MemberServiceImpl
    NotificationController -->|calls| NotificationServiceImpl
    DailyActivityController -->|calls| DailyActivityServiceImpl
    ImageTestController -->|calls| ImageServiceImpl
    WishController -->|calls| WishServiceImpl
    AuthController -->|calls| RefreshTokenServiceImpl

    ChatWebSocketController -->|calls| ChatServiceImpl
    NotificationMessageListener -->|publishes/receives| NotificationServiceImpl

    AuctionServiceImpl -->|uses| DomainEntities
    BidServiceImpl -->|uses| DomainEntities
    ChatServiceImpl -->|uses| DomainEntities
    MemberServiceImpl -->|uses| DomainEntities
    NotificationServiceImpl -->|uses| DomainEntities
    WishServiceImpl -->|uses| DomainEntities
    RefreshTokenServiceImpl -->|uses| DomainEntities
    DailyActivityServiceImpl -->|uses| DomainEntities
    ImageServiceImpl -->|uses| DomainEntities

    DomainEntities -->|persist via JPA| JPAAdapters
    DomainEntities -->|cache via Redis| RedisAdapters
    ImageServiceImpl -->|S3 API| S3Manager
    AuthController -->|JWT| OAuth2JWT
    AuctionServiceImpl -->|schedule| Scheduler
    BidServiceImpl -->|publish AMQP| MsgAdapters
    NotificationServiceImpl -->|publish AMQP| MsgAdapters

    JPAAdapters -->|JDBC| RDBMS
    RedisAdapters -->|Redis Protocol| RedisCache
    S3Manager -->|S3 API| S3Bucket
    OAuth2JWT -->|OAuth2 APIs| OAuth2Prov
    MsgAdapters -->|AMQP/Kafka| MsgBroker
    Scheduler -->|AMQP| MsgBroker

    %% Click Events
    click AuctionController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/auction/ui/web/AuctionController.java"
    click BidController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/bid/ui/web/BidController.java"
    click ChatController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/chat/ui/web/ChatController.java"
    click MemberController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/member/ui/MemberController.java"
    click NotificationController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/notification/ui/controller/NotificationController.java"
    click DailyActivityController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/daily/ui/DailyActivityController.java"
    click ImageTestController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/global/s3/ui/controller/ImageTestController.java"
    click WishController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/wish/ui/controller/WishController.java"
    click AuthController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/auth/ui/AuthController.java"
    click ChatWebSocketController "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/chat/ui/message/ChatWebSocketController.java"
    click NotificationMessageListener "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/notification/ui/websocket/NotificationMessageListener.java"
    click AuctionServiceImpl "https://github.com/023-dev/biram/tree/main/src/main/java/com/example/biram/module/auction/application/service"
    click BidServiceImpl "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/bid/application/service/BidServiceImpl.java"
    click ChatServiceImpl "https://github.com/023-dev/biram/tree/main/src/main/java/com/example/biram/module/chat/application/service"
    click DailyActivityServiceImpl "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/daily/application/DailyActivityServiceImpl.java"
    click ImageServiceImpl "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/image/application/service/ImageServiceImpl.java"
    click MemberServiceImpl "https://github.com/023-dev/biram/tree/main/src/main/java/com/example/biram/module/member/application"
    click NotificationServiceImpl "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/notification/application/service/NotificationServiceImpl.java"
    click WishServiceImpl "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/wish/application/service/WishServiceImpl.java"
    click RefreshTokenServiceImpl "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/auth/application/RefreshTokenServiceImpl.java"
    click JPAAdapters "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/auction/infrastructure/persistence/AuctionRepositoryImpl.java"
    click RedisAdapters "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/auction/infrastructure/cache/AuctionCacheImpl.java"
    click S3Manager "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/global/s3/application/manager/AmazonS3Manager.java"
    click OAuth2JWT "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/global/security/oauth2/OAuth2TokenLoginAuthenticationFilter.java"
    click MsgAdapters "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/bid/infrastructure/message/BidMessagePublisherImpl.java"
    click Scheduler "https://github.com/023-dev/biram/blob/main/src/main/java/com/example/biram/module/auction/infrastructure/scheduler/AuctionSchedulerImpl.java"

    %% Styles
    classDef ui fill:#D6E9FE,stroke:#4A90E2,stroke-width:1px
    classDef app fill:#DFF6DD,stroke:#27AE60,stroke-width:1px
    classDef domain fill:#FFF4D6,stroke:#F5A623,stroke-width:1px
    classDef infra fill:#E8E8E8,stroke:#7F8C8D,stroke-width:1px
    classDef external fill:#F3E5F5,stroke:#8E44AD,stroke-width:1px
```
