🎓 AI 기반 개인화 추천 및 콘텐츠 필터링 스터디 매칭 플랫폼

Capstone Design Project

Study With Me: 하이브리드 추천 알고리즘과 실시간 콘텐츠 필터링을 활용한 지능형 학습 커뮤니티 플랫폼

개발 기간: 2025.03 ~ 2026. 03

프로젝트 유형: 캡스톤 디자인

분야: 웹 애플리케이션, , AI/ML, 추천 시스템, 자연어 처리

프로젝트 개요

연구 주제

"활동 로그 기반 하이브리드 추천 시스템과 실시간 콘텐츠 필터링을 결합한 지능형 스터디 매칭 플랫폼 구현"

핵심 문제 정의

정보 과부하 문제: 기존 스터디 매칭 플랫폼에서는 사용자가 원하는 정보를 찾기 위해 많은 시간을 소요
비개인화 추천: 모든 사용자에게 동일한 콘텐츠를 제공하여 사용자 만족도 저하
악성 콘텐츠 관리: 수동 검토로 인한 악성 게시글/댓글 관리의 비효율성
콜드 스타트 문제: 신규 사용자나 활동이 적은 사용자에 대한 추천 정확도 저하

연구 목표

개인화 추천 시스템 구축: 사용자 활동 로그를 분석한 하이브리드 추천 알고리즘 구현
실시간 콘텐츠 필터링: 룰 기반 및 패턴 매칭을 활용한 자동 악성 콘텐츠 차단
AI 기반 콘텐츠 분석: 게시글 자동 태그 분류 및 요약 시스템 개발
확장 가능한 아키텍처: 마이크로서비스 구조를 고려한 모듈화된 시스템 설계

연구 기여도

학술적 기여: 하이브리드 추천 알고리즘의 실무 적용 사례 제시
실용적 기여: 실제 사용 가능한 스터디 매칭 플랫폼 제공
기술적 기여: Spring Boot와 Python AI 시스템의 효율적인 통합 방법 제안

연구 배경 및 목적

배경

온라인 학습 커뮤니티의 급속한 성장과 함께, 사용자에게 적합한 스터디 그룹이나 학습 자료를 추천하는 시스템의 중요성이 증가하고 있습니다. 특히 COVID-19 이후 비대면 학습 환경이 확산되면서, 개인화된 추천 시스템의 필요성이 더욱 부각되었습니다. 2025년 이후부터 끊임없이 학습하며 도전하는 사람들이 늘고있는만큼, 어플리케이션에 쌓이는 정보와 데이터들은 너무나 방대합니다. 그 정보들을 일일히 찾지않고 개인 AI툴이 항상 작동하여 어플리케이션 이동시, 본인의 학습 로드맵을 직접 짜주고 유사도를 계산하여 유저 친화적인 어플리케이션을 개발합니다.

기존 연구에서는 주로 단일 추천 기법(협업 필터링 또는 콘텐츠 기반 필터링)을 적용하는 경우가 많았으나, 이러한 접근 방식은 한계가 있습니다:

협업 필터링: 콜드 스타트 문제, 희소성 문제
콘텐츠 기반 필터링: 새로운 콘텐츠에 대한 다양성 부족

연구 목적

본 연구는 다음과 같은 목적을 가집니다:

하이브리드 추천 시스템 개발: 콘텐츠 기반 필터링, 협업 필터링, 인기도 기반 추천을 결합한 하이브리드 알고리즘 설계 및 구현
실시간 콘텐츠 필터링: 정규표현식 기반 패턴 매칭과 키워드 필터링을 통한 자동 악성 콘텐츠 감지 및 차단
활동 로그 기반 개인화: 사용자의 모든 활동(검색, 클릭, 좋아요, 북마크 등)을 수집하여 선호도 모델 구축
확장 가능한 시스템 설계: 향후 딥러닝 모델 통합을 고려한 모듈화된 아키텍처 제안

시스템 아키텍처

전체 시스템 구조

참고: 위 이미지의 ai_summary.py 설명은 "규칙 기반 구조화된 요약"으로 업데이트되었습니다.

┌─────────────────────────────────────────────────────────────┐
│                      클라이언트 (Web Browser)                 │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP/HTTPS
┌──────────────────────▼──────────────────────────────────────┐
│              Spring Boot Application (Java 21)               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Controller Layer (도메인별 MVC·REST)                    │ │
│  │  - HomeController, PostWebController, UserWebController │ │
│  │  - AdminController, CommentApiController,              │ │
│  │    NotificationApiController, ChatbotController       │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Service Layer                                         │ │
│  │  - UserService, PostService, CommentService            │ │
│  │  - UserRecommendationService                           │ │
│  │  - ContentFilterService                                │ │
│  │  - AITagService, AISummaryService                      │ │
│  │  - PythonRecommendationService                         │ │
│  │  - ChatbotService                                      │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Repository Layer (JPA)                                │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  Config Layer                                          │ │
│  │  - SecurityConfig, PythonInitializer                  │ │
│  └────────────────────────────────────────────────────────┘ │
└──────────────────────┬──────────────────────────────────────┘
                       │ JDBC
┌──────────────────────▼──────────────────────────────────────┐
│              MySQL/MariaDB Database                          │
│  - users, user_profiles, posts, comments, study_groups       │
│  - user_activities, blocked_posts, blocked_comments         │
│  - filter_words, filter_keywords, filter_patterns            │
│  - ai_learning_data, chat_messages                          │
└─────────────────────────────────────────────────────────────┘
                       │ Process Execution
┌──────────────────────▼──────────────────────────────────────┐
│              Python AI System                                │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  ai_recommendation.py                                  │ │
│  │  - 협업 필터링 (User-based/Item-based CF)              │ │
│  │  - 콘텐츠 기반 필터링                                   │ │
│  │  - 하이브리드 추천 알고리즘                            │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  ai_tag_recommendation.py                              │ │
│  │  - TF-IDF 기반 태그 추출                                │ │
│  │  - 기술 스택 매칭                                      │ │
│  │  - 하이브리드 태그 추천                                │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  ai_tag_recommendation_deep.py                        │ │
│  │  - 딥러닝 기반 태그 분류 (선택적)                      │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  ai_summary.py                                         │ │
│  │  - TF-IDF 기반 요약                                     │ │
│  │  - TextRank 기반 요약                                   │ │
│  │  - 하이브리드 요약 알고리즘                            │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  config.py, logger.py, utils.py, metrics.py           │ │
│  │  exceptions.py                                         │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

데이터 흐름도

추천 시스템 데이터 흐름:

사용자 활동 → UserActivity 저장 → Python 추천 스크립트 실행 
→ 선호도 분석 → 추천 점수 계산 → 추천 게시글 반환

콘텐츠 필터링 데이터 흐름:

게시글/댓글 작성 → ContentFilterService 호출 
→ 필터 규칙 검사 → 차단/통과 결정 → 학습 데이터 저장

AI 태그 분류 데이터 흐름:

게시글 작성 → AITagService 호출 → Python 태그 분류 스크립트 실행 
→ 태그 추출 → 카테고리 분류 → DB 저장

핵심 기술 및 알고리즘

1. 하이브리드 추천 알고리즘

1.1 알고리즘 개요

본 시스템은 하이브리드 추천 시스템을 구현합니다:

협업 필터링 (Collaborative Filtering)
- User-based CF: 비슷한 사용자들이 좋아한 게시글 추천
- Item-based CF: 비슷한 게시글 추천
콘텐츠 기반 필터링 (Content-Based Filtering)
인기도 기반 추천 (Popularity-Based Recommendation)
하이브리드 결합: 협업 필터링(60%) + 콘텐츠 기반(40%)

1.2 협업 필터링 알고리즘

User-based Collaborative Filtering:

비슷한 취향을 가진 사용자들을 찾아 그들이 좋아한 게시글을 추천
유사도 계산: 코사인 유사도 또는 피어슨 상관계수 사용
```
similarity(u1, u2) = cosine(user_vector1, user_vector2)
```

예상 평점 계산:

predicted_rating = Σ(similarity_i × rating_i) / Σ|similarity_i|

Item-based Collaborative Filtering:

사용자가 좋아한 게시글과 유사한 게시글을 추천
게시글 간 유사도를 계산하여 추천
장점: 안정적이고 계산 효율적

사용자-아이템 행렬 구축:

사용자 활동 로그(SEARCH, CLICK, LIKE, BOOKMARK, COMMENT, AI_CLICK)를 가중치로 변환
좋아요와 북마크 데이터를 추가로 반영
0-5 스케일로 정규화하여 평점 행렬 생성

1.3 사용자 선호도 분석 알고리즘

가중치 기반 선호도 계산을 통해 사용자의 관심사를 수치화합니다:

action_weights = {
    'SEARCH': 1.0,       # 검색 행동
    'CLICK': 2.0,        # 클릭 행동
    'LIKE': 3.0,         # 좋아요
    'BOOKMARK': 4.0,     # 북마크 (높은 관심도)
    'COMMENT': 3.5,      # 댓글 작성 (적극적 참여)
    'AI_CLICK': 5.0,     # AI 추천 클릭 (최고 가중치)
    'RECOMMEND': 2.5     # 추천 받음
}

수식:

카테고리 점수 = Σ(액션 가중치 × 액션 횟수) / 총 가중치 합
태그 점수 = Σ(액션 가중치 × 태그 등장 횟수) / 총 가중치 합

알고리즘 특징:

시간 가중치 적용: 최근 활동일수록 높은 가중치 부여
정규화(Normalization): 0~1 사이의 값으로 변환하여 일관성 확보
다중 신호 통합: 다양한 사용자 행동을 통합하여 선호도 모델 구축

1.4 추천 점수 계산 알고리즘

다중 요소 점수화 (Multi-Factor Scoring) 방식을 사용합니다:

score = 0
# 1. 카테고리 매칭 점수 (최대 가중치)
if post['category'] in preferences['categories']:
    score += preferences['categories'][post['category']] * 100

# 2. 태그 매칭 점수
for tag in post_tags:
    if tag in preferences['tags']:
        score += preferences['tags'][tag] * 50

# 3. 인기도 점수 (콜드 스타트 대응)
score += (post['like_count'] or 0) * 2
score += (post['view_count'] or 0) * 0.1

# 4. 최신성 점수 (최근 7일 내면 보너스)
if days_old <= 7:
    score += 10

최종 추천 점수 수식:

추천 점수 = (카테고리 매칭 × 100) 
         + (태그 매칭 × 50) 
         + (좋아요 수 × 2) 
         + (조회수 × 0.1) 
         + (최신성 보너스)

알고리즘 복잡도:

시간 복잡도: O(n × m + k × log k)
- n: 사용자 활동 로그 수
- m: 평균 태그 수
- k: 후보 게시글 수
공간 복잡도: O(n + m + k)

1.5 하이브리드 추천 결합

협업 필터링과 콘텐츠 기반 필터링을 결합하여 최종 추천 점수를 계산합니다:

final_score = CF_score × 0.6 + Content_score × 0.4

User-based CF와 Item-based CF 결합:

CF_score = User_based_score × 0.6 + Item_based_score × 0.4

1.6 콜드 스타트 문제 해결

인기도 기반 폴백: 활동 로그가 부족한 신규 사용자에게는 인기 게시글 추천
시간 가중치 감소: 활동이 적은 사용자에게는 전체 기간 데이터 활용
카테고리 기반 초기 추천: 사용자가 선택한 카테고리 기반 추천 제공

2. 콘텐츠 필터링 알고리즘

2.1 3단계 필터링 시스템

욕설 필터 (Profanity Filter): 사전 기반 단어 매칭
키워드 필터 (Keyword Filter): 정확 매칭/부분 매칭/정규식 매칭
패턴 필터 (Pattern Filter): 정규표현식 기반 복합 패턴 감지

2.2 필터링 알고리즘

// 1단계: 욕설 단어 체크
for (FilterWord word : activeWords) {
    if (fullText.contains(word.getWord().toLowerCase())) {
        return BLOCKED;
    }
}

// 2단계: 키워드 체크 (EXACT, PARTIAL, REGEX)
switch (keyword.getKeywordType()) {
    case EXACT: matched = fullText.equals(kw); break;
    case PARTIAL: matched = fullText.contains(kw); break;
    case REGEX: matched = pattern.matcher(fullText).find(); break;
}

// 3단계: 패턴 체크 (정규표현식)
Pattern regexPattern = Pattern.compile(pattern.getPatternRegex());
boolean matched = regexPattern.matcher(text).find();

알고리즘 특징:

순차적 검사: 낮은 복잡도 필터부터 순차적으로 검사하여 성능 최적화
학습 데이터 저장: 차단된 콘텐츠를 학습 데이터로 저장하여 향후 ML 모델 학습에 활용
통계 추적: 키워드/패턴별 차단 횟수 통계를 수집하여 효과 측정

3. AI 태그 분류 시스템

3.1 하이브리드 태그 추천 알고리즘

TF-IDF 기반 태그 추출과 기술 스택 매칭을 결합한 하이브리드 시스템:

TF-IDF 기반 태그 추출
- 문서에서 중요한 키워드를 TF-IDF로 추출
- Term Frequency (TF): 단어가 문서에 등장하는 빈도
- Inverse Document Frequency (IDF): 단어의 희귀도
- 상위 15개 키워드를 태그 후보로 선택
기술 스택 매칭
- 사전 정의된 기술 태그 목록과 텍스트 매칭
- Java, Python, Spring, React 등 기술 스택 자동 인식
- 최고 신뢰도(0.95) 부여
키워드 빈도 분석
- 자주 등장하는 단어를 태그로 추천
- 빈도 기반 점수 계산
카테고리 기반 추론
- 추천된 카테고리와 관련된 키워드를 태그로 추가
제목 가중치
- 제목에 등장하는 키워드에 추가 가중치 부여

최종 태그 선택: 점수 0.5 이상인 태그만 선택, 상위 10개 반환

알고리즘 복잡도:

시간 복잡도: O(n + c × k + t + m)
- n: 텍스트 길이
- c: 카테고리 수
- k: 키워드 수
- t: 기술 태그 수
- m: TF-IDF 계산 복잡도

4. 텍스트 요약 알고리즘

4.1 하이브리드 요약 알고리즘

TF-IDF, TextRank, 규칙 기반 추출을 결합한 하이브리드 요약 시스템:

TF-IDF 기반 요약
- 문서에서 중요한 키워드를 추출
- 키워드를 포함한 문장에 높은 점수 부여
- 상위 3개 문장을 원래 순서대로 정렬하여 요약 생성
- 수식:
```
sentence_score = Σ(TF-IDF(keyword)) / √(sentence_length)
```
TextRank 기반 요약
- PageRank 알고리즘을 텍스트에 적용
- 문장 간 유사도를 그래프로 표현
- 문장의 중요도를 반복 계산으로 수렴
- 수식:
```
score(sent_i) = (1 - d) + d × Σ(score(sent_j) × similarity(sent_j, sent_i) / out_degree(sent_j))
```
  - d: damping factor (기본값: 0.85)
하이브리드 결합
- TF-IDF 점수와 TextRank 점수를 가중 평균
- combined_score = TF-IDF_score × 0.5 + TextRank_score × 0.5
- 상위 3개 문장을 선택하여 요약 생성
규칙 기반 구조화된 정보 추출
- 정규표현식 패턴 매칭을 통한 정보 추출
- 사용자 프로필 정보 ("이런 사람을 원함", "원하는 사람", "참여 대상", "모집 대상")
- 추정 레벨 (초급/중급/고급) - 키워드 매칭 기반
- 진행 방식 ("진행 방식", "일정" 등)
- 레벨 추정:
  - 초급: 초보, 입문, 기초, 처음, 신입, 비전공
  - 중급: 중급, 중간, 어느정도, 경험, 실무
  - 고급: 고급, 심화, 전문, 시니어, 리드, 아키텍트

프로세스:

게시글 본문 → 텍스트 정리 (HTML 태그 제거) 
→ TF-IDF 키워드 추출 → 문장 점수 계산
→ TextRank 문장 중요도 계산
→ 하이브리드 점수 결합
→ 정규표현식으로 구조화된 정보 추출 
→ 레벨 추정 → 구조화된 요약 생성

4.2 알고리즘 비교

알고리즘	장점	단점	사용 시기
TF-IDF	빠름, 키워드 중심	문맥 고려 부족	짧은 문서
TextRank	문맥 고려, 문장 관계 반영	계산 비용 높음	긴 문서
Hybrid	정확도 높음	계산 비용 높음	일반적인 경우

4.3 향후 개선 방향

향후 Gemini API 기반 추상적 요약으로 업그레이드 예정:

의미 기반 요약 생성
더 정확한 구조화된 정보 추출
자연어 이해를 통한 고품질 요약

주요 기능

1. 사용자 관리 및 인증

회원가입/로그인: Spring Security 기반 세션 관리
비밀번호 암호화: BCrypt 해시 알고리즘 사용
역할 기반 접근 제어: ROLE_USER, ROLE_ADMIN

2. 게시글 관리 시스템

CRUD 기능: 게시글 생성, 조회, 수정, 삭제
카테고리 및 태그: 카테고리 분류 및 태그 시스템
좋아요/북마크: 사용자 반응 기능
검색 및 필터링: 제목, 내용, 카테고리 기반 검색

3. 댓글 시스템

댓글 작성/수정/삭제: 기본 CRUD 기능
대댓글 지원: 계층형 댓글 구조
댓글 좋아요: 사용자 참여 기능
실시간 필터링: 댓글 작성 시 자동 악성 콘텐츠 감지

4. AI 기반 개인화 추천

맞춤형 게시글 추천: 사용자 활동 로그 기반 추천
스터디 그룹 추천: 관심사 기반 스터디 그룹 매칭
스터디 파트너 추천: 게시글별 적합한 파트너 추천
실시간 업데이트: 사용자 활동 반영 추천 갱신

5. 스터디 그룹 관리

그룹 생성 및 관리: 목표, 일정, 최대 인원 설정
멤버 관리: 그룹장 권한 관리, 멤버 초대/수락
게시글 연동: 스터디 그룹 관련 게시글 작성 및 지원 관리

6. 콘텐츠 필터링

실시간 악성 콘텐츠 감지: 게시글/댓글 작성 시 자동 검사
3단계 필터링: 욕설 → 키워드 → 패턴 순차 검사
자동 차단 및 알림: 문제 콘텐츠 자동 차단 및 관리자 알림
학습 데이터 수집: 차단된 콘텐츠를 학습 데이터로 저장

7. AI 콘텐츠 분석

자동 태그 분류:
- TF-IDF 기반 키워드 추출
- 기술 스택 자동 매칭
- 하이브리드 태그 추천 시스템
본문 요약:
- TF-IDF 기반 키워드 중요도 요약
- TextRank 기반 문장 중요도 요약
- 하이브리드 요약 알고리즘
- 구조화된 정보 추출 (사용자 프로필, 레벨, 진행 방식)
신뢰도 제공: 분류 및 요약 결과의 신뢰도 점수 제공

8. AI 챗봇 시스템

대화형 AI 어시스턴트: Gemini API 기반 자연어 대화 지원
컨텍스트 인식: 최근 대화 기록을 기반으로 맥락 파악
액션 지원: 게시글 검색, 마이페이지 이동 등 액션 실행
대화 기록 저장: 사용자별 대화 기록 저장 및 관리

9. 사용자 활동 추적

활동 로그 수집: 검색, 클릭, 좋아요, 북마크 등 모든 활동 기록
통계 및 분석: 개인별 활동 통계 및 선호도 분석
맞춤형 대시보드: 마이페이지에서 개인 활동 요약 확인

10. 관리자 기능

차단된 콘텐츠 관리: 악성 게시글/댓글 검토 및 처리
필터 규칙 관리: 필터 키워드, 패턴, 단어 관리
AI 학습 데이터 관리: AI 학습에 사용된 데이터 확인
사용자 통계: 플랫폼 이용 통계 및 분석

11. 자동 환경 초기화

Python 환경 자동 검증: 애플리케이션 시작 시 Python 스크립트 및 패키지 확인
문법 검사: 모든 Python 파일의 문법 오류 사전 검사
테스트 실행: 실행 가능한 스크립트들의 기본 기능 테스트
설정 스크립트: setup.sh/setup.bat을 통한 자동 환경 설정

기술 스택

백엔드

기술	버전	용도	선택 이유
Java	21 LTS	백엔드 개발 언어	최신 LTS 버전, 강력한 타입 안정성
Spring Boot	3.3.4	웹 프레임워크	빠른 개발, 풍부한 생태계, 프로덕션 레디
Spring Data JPA	3.3.4	데이터베이스 ORM	객체-관계 매핑, 복잡한 쿼리 지원
Spring Security	6.x	인증/인가	강력한 보안 기능, 세션 관리
Thymeleaf	3.x	템플릿 엔진	서버 사이드 렌더링, 자연스러운 HTML

데이터베이스

기술	버전	용도	선택 이유
MySQL/MariaDB	8.0+	관계형 데이터베이스	안정성, 높은 성능, ACID 트랜잭션
JPA/Hibernate	-	ORM 프레임워크	객체 중심 개발, 자동 쿼리 생성

AI/ML 시스템

기술	버전	용도	선택 이유
Python	3.7+	AI 스크립트 언어	풍부한 ML 라이브러리, 데이터 처리
Google Gemini API	v1beta	챗봇	고품질 자연어 처리, 대화형 AI 지원
mysql-connector-python	-	DB 연결	MySQL과의 효율적인 통신
Collections	-	데이터 구조	Counter, defaultdict 등 효율적인 자료구조
torch, transformers	-	딥러닝 (선택적)	딥러닝 기반 태그 분류 (향후 확장)

인프라 및 도구

기술	용도	선택 이유
Docker & Docker Compose	개발 환경 자동화	일관된 환경, 쉬운 배포
Gradle	빌드 도구	빠른 빌드, 의존성 관리
Git	버전 관리	협업, 코드 히스토리 관리

프론트엔드

기술	용도	선택 이유
HTML5 / CSS3	구조 및 스타일	표준 웹 기술
JavaScript	클라이언트 로직	동적 인터랙션, API 통신
Thymeleaf	서버 사이드 렌더링	SEO 최적화, 빠른 렌더링

프로젝트 구조

백엔드는 도메인(바운디드 컨텍스트)별 패키지로 구성합니다. 각 도메인 아래에 entity → repository → service → (필요 시) application → controller 순으로 두어, 포트폴리오·실무에서 말하는 기능 단위 모듈와 대응시키기 쉽습니다. (단일 Spring Boot 애플리케이션, 단일 DB.)

도메인	역할
`user`	회원·프로필·활동·온라인·통계·추천(Java↔Python 연동)
`board`	게시글·좋아요·북마크·지원·자격증 일정·메인 피드
`comment`	댓글·댓글 API
`studygroup`	스터디 그룹·캘린더·채팅·목표·출석·관리 API
`studysession`	개인 학습 세션·학습 일지 화면
`notification`	알림
`moderation`	필터·차단·관리자
`ai`	태그/요약·챗봇·Python 실행기·게시글 연동 REST
`config`	Security, Python 초기화

계층 규칙 (요약)

controller: HTTP, 세션, 뷰 이름·리다이렉트만 담당.
application (선택): 한 화면/시나리오에 필요한 여러 서비스·리포지토리 조합과 트랜잭션 경계. 예: user.application.UserOnboardingApplicationService (AI 온보딩 카테고리 저장).
service: 단일 도메인 규칙·도메인 로직.
repository / entity: 영속성.

도메인 간 의존 관계 (참고)

화살표는 상위 패키지가 하위를 사용(참조)한다는 뜻입니다. 순환을 피하려면 새 기능은 가능한 한 한 방향으로만 호출하는 것이 좋습니다.

flowchart TB
  subgraph core["핵심"]
    user[("user")]
    board[("board")]
  end
  subgraph collab["협업·세션"]
    comment[("comment")]
    studygroup[("studygroup")]
    studysession[("studysession")]
  end
  subgraph platform["플랫폼·AI"]
    notification[("notification")]
    moderation[("moderation")]
    ai[("ai")]
  end
  board --> user
  comment --> board
  comment --> user
  comment --> notification
  comment --> moderation
  studygroup --> board
  studygroup --> user
  studygroup --> notification
  studysession --> studygroup
  studysession --> user
  notification --> user
  moderation --> board
  moderation --> user
  moderation --> ai
  ai --> board
  ai --> user
  user --> board
  user --> ai

studywithmever2/
├── src/main/java/com/example/studywithme/
│   ├── StudyWithMeApplication.java
│   ├── config/
│   │   ├── SecurityConfig.java
│   │   └── PythonInitializer.java
│   ├── user/                 # entity, repository, service, application, controller
│   ├── board/                # entity, repository, service, controller (HomeController, PostWebController)
│   ├── comment/
│   ├── studygroup/
│   ├── studysession/
│   ├── notification/
│   ├── moderation/
│   └── ai/                   # AiPostApiController, ChatbotController 등
│
├── src/main/resources/
│   ├── application.properties           # Spring Boot 설정
│   ├── static/                          # 정적 파일
│   │   ├── css/                         # 스타일시트
│   │   └── js/                          # JavaScript
│   └── templates/                       # Thymeleaf 템플릿
│       ├── index.html                   # 메인 페이지
│       ├── auth.html                    # 로그인/회원가입
│       ├── post-*.html                  # 게시글 관련
│       ├── admin-*.html                 # 관리자 페이지
│       └── ...
│
├── python/                              # Python AI 시스템
│   ├── ai_recommendation.py             # 협업 필터링 + 콘텐츠 기반 하이브리드 추천
│   ├── ai_tag_recommendation.py         # TF-IDF 기반 하이브리드 태그 추천
│   ├── ai_tag_recommendation_deep.py    # 딥러닝 태그 분류 (선택적)
│   ├── ai_summary.py                    # TF-IDF + TextRank 하이브리드 요약
│   ├── config.py                        # 설정 파일
│   ├── utils.py                         # 유틸리티 함수
│   ├── logger.py                        # 로깅 설정
│   ├── metrics.py                       # 성능 지표
│   ├── exceptions.py                    # 예외 처리
│   ├── requirements.txt                 # Python 의존성
│   ├── README.md                        # Python 시스템 문서
│   ├── PythonREADME.md                  # 알고리즘 상세 문서 (신규)
│   ├── ALGORITHM_ANALYSIS.md            # 알고리즘 상세 분석
│   └── CODE_REVIEW.md                   # 코드 리뷰
│
├── docker-compose.yml                   # Docker Compose 설정
├── studywithmever2.sql                  # 데이터베이스 초기화 스크립트
├── chat_messages_table.sql             # 챗봇 메시지 테이블 스크립트
├── setup.sh                             # 자동 설정 스크립트 (Mac/Linux)
├── setup.bat                             # 자동 설정 스크립트 (Windows)
├── build.gradle                         # Gradle 빌드 설정
├── README.md                            # 본 문서
├── QUICK_START.md                       # 빠른 시작 가이드
├── SETUP.md                             # 상세 설치 가이드
├── PROJECT_ROADMAP.md                   # 프로젝트 로드맵
├── scripts/                             # 유지보수용 스크립트
│   ├── migrate_domain_packages.ps1      # 도메인 패키지 일괄 이동 (참고)
│   └── migrate_domain_packages.py
└── docs/backend-portfolio/              # 도메인별 백엔드 포트폴리오 문서 (API·흐름·Postman·트러블슈팅)
    └── README.md                        # 목차 및 링크

백엔드 포트폴리오 문서 바로가기: docs/backend-portfolio/README.md · 트러블슈팅·Postman 첨부

설치 및 실행

필수 요구사항

Java 21+ (Gradle Wrapper가 자동 설치)
Docker & Docker Compose (MySQL 자동 설치용, 권장)
Python 3.7+ (AI 시스템 실행용, 선택사항)
Git

빠른 시작 (권장)

자동 설정 스크립트를 사용하면 모든 설정이 자동으로 완료됩니다:

Mac/Linux:

git clone https://github.com/study-withme/ai-website-studywithme.git
cd ai-website-studywithme
chmod +x setup.sh
./setup.sh
./gradlew bootRun

Windows:

git clone https://github.com/study-withme/ai-website-studywithme.git
cd ai-website-studywithme
setup.bat
gradlew.bat bootRun

자동 설정 스크립트가 다음을 수행합니다:

✅ application.properties 파일 생성 및 DB 비밀번호 설정
✅ Python 패키지 자동 설치
✅ Docker Compose로 데이터베이스 자동 시작 (Docker 설치 시)
✅ 필요한 설정 확인

📖 자세한 설치 가이드: QUICK_START.md 또는 SETUP.md 참고

수동 설치

1. 프로젝트 클론

git clone https://github.com/study-withme/ai-website-studywithme.git
cd ai-website-studywithme

2. 애플리케이션 설정

# 설정 파일 복사
cp src/main/resources/application.properties.example src/main/resources/application.properties

# application.properties 파일을 열어서 DB 비밀번호 및 Gemini API 키 설정
# - db.password=your_password_here → 실제 비밀번호로 변경
# - gemini.api.key=your_gemini_api_key_here → Gemini API 키 설정

3. 데이터베이스 설정

Docker 사용 (권장):

docker compose up -d db

로컬 MySQL 사용:

mysql -u root -p
CREATE DATABASE studywithmever2 CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
source studywithmever2.sql;
source chat_messages_table.sql;  # 챗봇 기능 사용 시

4. Python AI 시스템 설정 (선택)

cd python
pip install -r requirements.txt

💡 Python이 설치되어 있지 않아도 웹사이트는 정상 동작합니다. (AI 기능만 제한됨)

5. 애플리케이션 실행