OFF 프로젝트 기술 문서

프로젝트 파트너 매칭 플랫폼

📚 목차

기술 스택
서버 아키텍처
ERD (Entity Relationship Diagram)
주요 기능
외부 API 연동

1. 기술 스택

🔧 Backend

분류	기술	버전	용도
Language	Java	21	개발 언어
Framework	Spring Boot	3.5.9	애플리케이션 프레임워크
Build Tool	Gradle	-	빌드 및 의존성 관리
ORM	Spring Data JPA	-	데이터베이스 접근
Database	PostgreSQL	-	관계형 데이터베이스 (AWS RDS)
Security	JWT (JJWT)	0.12.5	인증/인가
	Spring Security Crypto	-	비밀번호 암호화 (BCrypt)
Validation	Jakarta Validation	-	요청 데이터 검증
Real-time	WebSocket (STOMP)	-	실시간 채팅
Documentation	Swagger (Springdoc)	2.8.5	API 문서화

☁️ Infrastructure & DevOps

분류	기술	용도
Cloud	AWS EC2	애플리케이션 서버
	AWS RDS (PostgreSQL)	데이터베이스 서버
CI/CD	GitHub Actions	자동 빌드 및 배포
VCS	Git / GitHub	버전 관리

🔗 External APIs

API	용도	버전
Google Gemini API	AI 기반 프로젝트 견적 및 Task 자동 생성	-
Toss Payments API	파트너 매칭 결제	-

📦 주요 Dependencies

// Core
- Spring Boot Starter Web
- Spring Boot Starter Data JPA
- Spring Boot Starter Validation
- Spring Boot Starter WebSocket

// Security
- JJWT (JWT 인증)
- Spring Security Crypto (비밀번호 암호화)

// Database
- PostgreSQL Driver
- H2 Database (테스트용)

// Documentation
- Springdoc OpenAPI (Swagger)

// External Integration
- WebFlux (Toss Payments, Gemini API 연동)

// Utilities
- Lombok (보일러플레이트 코드 제거)
- Jackson (JSON 직렬화/역직렬화)

2. 서버 아키텍처

🏗️ 전체 아키텍처

┌─────────────────────────────────────────────────────────────┐
│                         Client Layer                         │
│                    (Web / Mobile App)                        │
└────────────────────────────┬────────────────────────────────┘
                             │ HTTP/HTTPS
                             │ WebSocket
┌────────────────────────────▼────────────────────────────────┐
│                      Presentation Layer                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              REST API Controllers                     │  │
│  │  - MemberController  - ProjectController             │  │
│  │  - ChatController    - PayController                 │  │
│  │  - PartnerMatchingController                         │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │            JWT Authentication Filter                  │  │
│  │       (JwtAuthenticationFilter)                      │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│                       Business Layer                         │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                Service Components                     │  │
│  │  - MemberService      - ProjectService               │  │
│  │  - ChatService        - PayFacade/PayLogService      │  │
│  │  - PartnerMatchingService                            │  │
│  │  - NotificationService                               │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│                      Persistence Layer                       │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              JPA Repositories                         │  │
│  │  - MemberRepository  - ProjectRepository             │  │
│  │  - ChatRoomRepository                                │  │
│  │  - PartnerApplicationRepository                      │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                  JPA Entities                         │  │
│  │  - Member  - Project  - ChatRoom  - PayLog          │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────┬────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────┐
│                      Database Layer                          │
│              PostgreSQL (AWS RDS)                            │
└──────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      External Services                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Gemini API   │  │Toss Payments│  │ AWS Services │     │
│  │ (AI 견적)    │  │   (결제)     │  │  (EC2/RDS)   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

📂 패키지 구조 (Domain-Driven Design)

com.example.off
│
├── common/                     # 공통 모듈
│   ├── config/                 # 설정 (PasswordConfig, FilterConfig)
│   ├── exception/              # 예외 처리 (OffException, OffControllerAdvice)
│   ├── response/               # 통합 응답 형식 (BaseResponse, ResponseCode)
│   ├── jwt/                    # JWT 인증 (JwtTokenProvider, Filter)
│   ├── gemini/                 # Gemini API 연동
│   ├── infra/                  # 외부 인프라 (TossPaymentsClient)
│   └── swagger/                # Swagger 설정
│
├── domain/                     # 도메인 계층 (DDD)
│   ├── member/                 # 회원 도메인
│   │   ├── Member.java         # 엔티티
│   │   ├── controller/         # API 컨트롤러
│   │   ├── service/            # 비즈니스 로직
│   │   ├── repository/         # 데이터 접근
│   │   └── dto/                # 데이터 전송 객체
│   │
│   ├── project/                # 프로젝트 도메인
│   │   ├── Project.java
│   │   ├── controller/
│   │   ├── service/            # 견적, 확정, Task 생성
│   │   ├── repository/
│   │   └── dto/
│   │
│   ├── partnerRecruit/         # 파트너 모집/매칭 도메인
│   │   ├── PartnerRecruit.java
│   │   ├── PartnerApplication.java
│   │   ├── controller/
│   │   ├── service/
│   │   └── dto/
│   │
│   ├── chat/                   # 채팅 도메인 (WebSocket)
│   │   ├── ChatRoom.java
│   │   ├── Message.java
│   │   ├── controller/
│   │   ├── service/
│   │   └── dto/
│   │
│   ├── pay/                    # 결제 도메인
│   │   ├── PayLog.java
│   │   ├── controller/
│   │   ├── service/            # PayLogService, PayFacade
│   │   └── dto/
│   │
│   ├── notification/           # 알림 도메인
│   ├── task/                   # Task 관리 도메인
│   ├── projectMember/          # 프로젝트 멤버 도메인
│   └── role/                   # 역할 도메인 (PM, DEV, DES, MAR)
│
└── OffApplication.java         # 메인 애플리케이션

🔄 요청 처리 흐름

1. Client Request
   ↓
2. JwtAuthenticationFilter (JWT 검증 → memberId 추출)
   ↓
3. Controller (요청 수신, Validation)
   ↓
4. Service (비즈니스 로직 처리)
   ↓
5. Repository (데이터베이스 접근)
   ↓
6. Entity (JPA 영속성 관리)
   ↓
7. Database (PostgreSQL)
   ↓
8. Response (BaseResponse<T> 형식)
   ↓
9. Client

🎯 설계 원칙

Layered Architecture + DDD

Presentation Layer: REST API, WebSocket
Business Layer: 도메인별 Service
Persistence Layer: JPA Repository
Database Layer: PostgreSQL

Entity 설계 패턴

@Entity
@Getter
@NoArgsConstructor
public class Member {
    @Id @GeneratedValue
    private Long id;

    // Private constructor
    private Member(...) { ... }

    // Static factory method
    public static Member of(...) { ... }

    // Business logic methods
    public void updateNickname(...) { ... }
}

DTO 패턴

Request DTO: @NotNull, @NotBlank 등 Validation
Response DTO: static of() factory method
통합 응답: BaseResponse<T>

예외 처리

throw new OffException(ResponseCode.MEMBER_NOT_FOUND);
↓
@RestControllerAdvice
public class OffControllerAdvice {
    @ExceptionHandler(OffException.class)
    public ResponseEntity<BaseResponse<Void>> handle(...) { ... }
}

3. ERD

📊 주요 엔티티 관계

erDiagram
    MEMBER ||--o{ PROJECT : creates
    MEMBER ||--o{ PROJECT_MEMBER : participates
    MEMBER ||--o{ PARTNER_APPLICATION : applies
    MEMBER ||--o{ CHAT_ROOM_MEMBER : joins
    MEMBER ||--o{ MESSAGE : sends
    MEMBER ||--o{ NOTIFICATION : receives
    MEMBER ||--o{ PORTFOLIO : has
    MEMBER }o--|| MEMBER_ROLE : has

    PROJECT ||--o{ PROJECT_MEMBER : has
    PROJECT ||--o{ PARTNER_RECRUIT : posts
    PROJECT ||--o{ CHAT_ROOM : belongs_to
    PROJECT ||--o{ TASK : contains

    PARTNER_RECRUIT ||--o{ PARTNER_APPLICATION : receives

    PARTNER_APPLICATION ||--o| PAY_LOG : payment_for

    CHAT_ROOM ||--o{ CHAT_ROOM_MEMBER : has
    CHAT_ROOM ||--o{ MESSAGE : contains

    TASK ||--o{ TO_DO : has

    PROJECT_MEMBER ||--o{ TASK : assigned_to

📋 테이블 상세 설명

👤 회원 관련

member

id (PK): 회원 고유 ID
email: 이메일 (로그인 ID)
password: 암호화된 비밀번호 (BCrypt)
nickname: 닉네임
phone: 전화번호
profile_image: 프로필 이미지 URL
self_introduction: 자기소개
role: 역할 (PM, DEV, DES, MAR)
project_count: 프로젝트 경험 횟수
is_working: 현재 프로젝트 진행 중 여부
created_at, updated_at: 생성/수정 시간

portfolio

portfolio_id (PK)
member_id (FK → member)
title: 포트폴리오 제목
description: 설명
url: 포트폴리오 링크

📁 프로젝트 관련

project

project_id (PK)
creator_id (FK → member): 프로젝트 생성자 (기획자)
name: 프로젝트명
description: 설명
requirement: 요구사항
introduction: 프로젝트 소개
total_estimate: 총 예상 비용
start_date, end_date: 시작/종료일
project_type: 프로젝트 타입
status: 상태 (IN_PROGRESS, COMPLETED)

project_member

project_member_id (PK)
project_id (FK → project)
member_id (FK → member)
role: 프로젝트 내 역할

🤝 파트너 모집/매칭

partner_recruit

partner_recruit_id (PK)
project_id (FK → project)
role: 모집 역할 (DEV, DES, MAR)
number_of_person: 모집 인원
cost: 1인당 비용
recruit_status: 모집 상태 (OPEN, CLOSED)

partner_application

partner_application_id (PK)
partner_recruit_id (FK → partner_recruit)
member_id (FK → member): 지원자
application_status: 지원 상태 (WAITING, ACCEPT, REJECT)
is_from_project: 기획자 제안 여부 (true: 초대, false: 지원)

💬 채팅

chat_room

chat_room_id (PK)
project_id (FK → project, nullable): 프로젝트 채팅방인 경우
chat_type: 채팅 타입 (CONTACT: 1:1, PROJECT: 프로젝트)

chat_room_member

chat_room_member_id (PK)
chat_room_id (FK → chat_room)
member_id (FK → member)
last_read_at: 마지막 읽은 시간

message

message_id (PK)
chat_room_id (FK → chat_room)
member_id (FK → member): 발신자
content: 메시지 내용
is_read: 읽음 여부

💳 결제

pay_log

pay_log_id (PK)
order_id: Toss 주문 ID (UUID)
amount: 결제 금액
status: 결제 상태 (READY, PAID, FAILED, CANCELED)
payment_key: Toss 결제 키
payer_id (FK → member): 결제자 (기획자)
partner_application_id (FK → partner_application)
project_member_id (FK → project_member): 매칭 완료 시 생성

🔔 알림

notification

notification_id (PK)
member_id (FK → member): 수신자
message: 알림 메시지
url: 알림 클릭 시 이동 URL
notification_type: 알림 타입 (INVITE, APPLICATION, PAY, PROJECT_COMPLETE)
is_read: 읽음 여부

✅ Task 관리

task

task_id (PK)
project_id (FK → project)
project_member_id (FK → project_member): 담당자
name: Task 이름
description: Task 설명

to_do

to_do_id (PK)
task_id (FK → task)
content: ToDo 내용
is_done: 완료 여부

4. 주요 기능

🎯 핵심 기능 흐름

1️⃣ 프로젝트 생성 및 견적

1. 기획자: 프로젝트 견적 요청 (POST /projects/estimate)
   ↓
2. Gemini API 호출
   - 프로젝트 설명/요구사항 분석
   - 역할별 비용 산정
   - 예상 종료일 계산
   - 파트너 추천
   - 서비스 요약 생성
   ↓
3. 견적 결과 반환 (EstimateResponse)
   ↓
4. 기획자: 프로젝트 확정 (POST /projects/confirm)
   ↓
5. Project 생성 + PartnerRecruit 생성 + Task 자동 생성 (Gemini)

2️⃣ 파트너 매칭

시나리오 A: 파트너 지원

1. 파트너: 프로젝트 지원 (POST /projects/{id}/applications)
   ↓
2. PartnerApplication 생성 (status=WAITING)
   ↓
3. 기획자에게 알림 전송
   ↓
4. 기획자: 결제 진행 (prepare → confirm)
   ↓
5. ProjectMember 생성 + 매칭 완료

시나리오 B: 기획자 초대

1. 기획자: 파트너 초대 (POST /projects/{id}/invitations)
   ↓
2. PartnerApplication 생성 (isFromProject=true)
   ↓
3. 파트너에게 알림 전송
   ↓
4. 파트너: 수락 (POST /invitations/{id}/accept)
   ↓
5. 기획자에게 결제 알림
   ↓
6. 기획자: 결제 진행
   ↓
7. ProjectMember 생성 + 매칭 완료

3️⃣ 실시간 채팅 (WebSocket + STOMP)

1. 첫 메시지 전송 (POST /chat/rooms/first)
   - ChatRoom 생성
   - ChatRoomMember 2명 추가
   - ChatType 자동 결정 (CONTACT or PROJECT)
   ↓
2. WebSocket 연결 (/ws-stomp)
   ↓
3. 메시지 발행 (/pub/chat/message)
   ↓
4. 구독자에게 브로드캐스트 (/sub/chat/room/{roomId})
   ↓
5. 안 읽은 메시지 알림 (/queue/unread-status)

4️⃣ Toss Payments 결제

1. 기획자: 결제 준비 (POST /payments/prepare)
   - PayLog 생성 (status=READY)
   - orderId, amount 반환
   ↓
2. 프론트: Toss 위젯 초기화 (clientKey)
   ↓
3. 사용자 결제 진행
   ↓
4. Toss: successUrl로 리다이렉트 (paymentKey 전달)
   ↓
5. 프론트: 결제 확인 (POST /payments/confirm)
   - Toss API 최종 승인 요청
   - PayLog 상태 업데이트 (PAID)
   - ProjectMember 생성
   - 파트너에게 알림

🔐 인증/인가

1. 로그인 (POST /members/login)
   ↓
2. JWT 토큰 발급 (accessToken, refreshToken)
   ↓
3. API 요청 시 Header: Authorization: Bearer {token}
   ↓
4. JwtAuthenticationFilter
   - 토큰 검증
   - memberId 추출
   - HttpServletRequest에 저장
   ↓
5. Controller에서 memberId 사용

5. 외부 API 연동

🤖 Google Gemini API

용도:

프로젝트 견적 자동 산정
파트너 추천 및 비용 차등 산정
Task 및 ToDo 자동 생성
서비스 상세 기획안 생성

구현:

@Service
public class GeminiService {
    private final WebClient geminiWebClient;

    public String generateText(String prompt) {
        // Gemini API 호출
        // JSON 응답 파싱
        // 결과 반환
    }
}

💳 Toss Payments API

용도: 파트너 매칭 결제

플로우:

준비 단계: PayLog 생성 (READY)
결제 단계: Toss 위젯 (클라이언트)
승인 단계: Toss API 호출 (서버) → PAID

구현:

@Component
public class TossPaymentsClient {
    private final WebClient tossWebClient;

    public TossPaymentConfirmResponse confirm(
        String paymentKey, String orderId, Long amount
    ) {
        // Toss API 승인 요청
        // Basic Auth (secretKey)
    }
}

📈 성능 최적화

N+1 쿼리 해결

@Query("SELECT m FROM Member m " +
       "JOIN FETCH m.portfolios " +
       "WHERE m.id = :id")
Optional<Member> findByIdWithPortfolios(@Param("id") Long id);

JOIN FETCH 활용

@Query("SELECT crm FROM ChatRoomMember crm " +
       "JOIN FETCH crm.chatRoom cr " +
       "LEFT JOIN FETCH cr.project " +
       "JOIN FETCH crm.member " +
       "WHERE crm.member.id = :memberId")
List<ChatRoomMember> findAllByMember_IdAndChatRoom_ChatType(...);

🚀 배포 프로세스

GitHub Actions CI/CD

on:
  push:
    branches: [ develop ]

jobs:
  build:
    - Gradle build
    - JAR 생성

  deploy:
    - EC2에 JAR 배포
    - 환경 변수 설정 (.env)
    - systemd로 앱 재시작

환경 변수 관리

로컬: .env 파일
배포: GitHub Secrets → EC2 .env 자동 생성

📝 API 명세

Swagger UI: /swagger-ui/index.html

통합 응답 형식:

{
  "success": true,
  "code": 200,
  "message": "요청에 성공하였습니다.",
  "data": { ... }
}

Name		Name	Last commit message	Last commit date
Latest commit History 246 Commits
.github		.github
gradle/wrapper		gradle/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
build.gradle		build.gradle
gradlew		gradlew
gradlew.bat		gradlew.bat
run.sh		run.sh
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

OFF 프로젝트 기술 문서

📚 목차

1. 기술 스택

🔧 Backend

☁️ Infrastructure & DevOps

🔗 External APIs

📦 주요 Dependencies

2. 서버 아키텍처

🏗️ 전체 아키텍처

📂 패키지 구조 (Domain-Driven Design)

🔄 요청 처리 흐름

🎯 설계 원칙

Layered Architecture + DDD

Entity 설계 패턴

DTO 패턴

예외 처리

3. ERD

📊 주요 엔티티 관계

📋 테이블 상세 설명

👤 회원 관련

📁 프로젝트 관련

🤝 파트너 모집/매칭

💬 채팅

💳 결제

🔔 알림

✅ Task 관리

4. 주요 기능

🎯 핵심 기능 흐름

1️⃣ 프로젝트 생성 및 견적

2️⃣ 파트너 매칭

3️⃣ 실시간 채팅 (WebSocket + STOMP)

4️⃣ Toss Payments 결제

🔐 인증/인가

5. 외부 API 연동

🤖 Google Gemini API

💳 Toss Payments API

📈 성능 최적화

N+1 쿼리 해결

JOIN FETCH 활용

🚀 배포 프로세스

GitHub Actions CI/CD

환경 변수 관리

📝 API 명세

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages