chore: 백엔드와 프론트엔드를 모노레포로 통합

.claude/commands/create-domain.md

@@ -24,7 +24,7 @@
 ## 생성할 파일 목록
 
 ### 1. Entity
-`src/main/java/com/opensource/docgrid/domain/{domain}/entity/{Domain}.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/entity/{Domain}.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.entity;
@@ -48,7 +48,7 @@ public class {Domain} extends BaseEntity {
 ```
 
 ### 2. Repository
-`src/main/java/com/opensource/docgrid/domain/{domain}/repository/{Domain}Repository.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/repository/{Domain}Repository.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.repository;
@@ -61,7 +61,7 @@ public interface {Domain}Repository extends JpaRepository<{Domain}, Long> {
 ```
 
 ### 3. QueryService
-`src/main/java/com/opensource/docgrid/domain/{domain}/service/query/{Domain}QueryService.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/service/query/{Domain}QueryService.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.service.query;
@@ -91,7 +91,7 @@ public class {Domain}QueryService {
 ```
 
 ### 4. CommandService
-`src/main/java/com/opensource/docgrid/domain/{domain}/service/command/{Domain}CommandService.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/service/command/{Domain}CommandService.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.service.command;
@@ -111,7 +111,7 @@ public class {Domain}CommandService {
 ```
 
 ### 5. Controller
-`src/main/java/com/opensource/docgrid/domain/{domain}/controller/{Domain}Controller.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/controller/{Domain}Controller.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.controller;
@@ -135,7 +135,7 @@ public class {Domain}Controller {
 ```
 
 ### 6. Request DTO
-`src/main/java/com/opensource/docgrid/domain/{domain}/dto/request/{Domain}Request.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/dto/request/{Domain}Request.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.dto.request;
@@ -145,7 +145,7 @@ public record {Domain}Request() {
 ```
 
 ### 7. Response DTO
-`src/main/java/com/opensource/docgrid/domain/{domain}/dto/response/{Domain}Response.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/dto/response/{Domain}Response.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.dto.response;
@@ -155,7 +155,7 @@ public record {Domain}Response() {
 ```
 
 ### 8. Converter
-`src/main/java/com/opensource/docgrid/domain/{domain}/converter/{Domain}Converter.java`
+`backend/src/main/java/com/opensource/docgrid/domain/{domain}/converter/{Domain}Converter.java`
 
 ```java
 package com.opensource.docgrid.domain.{domain}.converter;

.claude/rules/db-migration.md

@@ -1,5 +1,5 @@
 ---
-globs: "src/main/resources/db/migration/**"
+globs: "backend/src/main/resources/db/migration/**"
 ---
 
 # DB 마이그레이션 규칙

.claude/rules/docs-management.md

@@ -14,4 +14,4 @@ globs: "docs/**/*.md"
 - 위치: `docs/test-results/`
 - 파일명: 설계 문서와 동일한 이름 사용
 - 기능 머지 후 **별도 테스트 이슈**로 분리해서 작성
-- 반드시 포함: 정상 케이스 + 에러 케이스 **최소 1개** 시나리오, `./gradlew test` 결과
+- 반드시 포함: 정상 케이스 + 에러 케이스 **최소 1개** 시나리오, `./backend/gradlew -p backend test` 결과

.claude/rules/git-conventions.md

@@ -23,11 +23,11 @@
 
 ## 빌드
 ```bash
-./gradlew build -x test   # CI용 (테스트 제외)
-./gradlew build            # 전체 빌드 + 테스트
+./backend/gradlew -p backend build -x test   # CI용 (테스트 제외)
+./backend/gradlew -p backend build            # 전체 빌드 + 테스트
 ```
 
 ## 트러블슈팅
 - LazyInitializationException: 트랜잭션 범위 밖 연관관계 접근, JOIN FETCH 추가
 - PostgreSQL 연결 실패: `application-local.yml` DB 설정 및 PostgreSQL 실행 여부 확인
-- 빌드 실패: `./gradlew clean build` 후 재시도
+- 빌드 실패: `./backend/gradlew -p backend clean build` 후 재시도

.claude/rules/testing_guide.md

@@ -1,5 +1,5 @@
 ---
-globs: "src/test/**/*.java"
+globs: "backend/src/test/**/*.java"
 ---
 
 # 테스트 컨벤션
@@ -48,7 +48,7 @@ class XxxServiceTest {
 ```
 
 ## Fixture 클래스
-- 위치: `src/test/java/com/opensource/docgrid/{domain}/fixture/`
+- 위치: `backend/src/test/java/com/opensource/docgrid/{domain}/fixture/`
 - 상수: `public static final`
 - 팩토리 메서드: `public static`
 
@@ -71,4 +71,4 @@ public class XxxFixture {
 class XxxIntegrationTest { }
 ```
 - 반드시 `@Tag("integration")` 추가
-- `./gradlew test -Dgroups=integration` 으로 분리 실행
+- `./backend/gradlew -p backend test -Dgroups=integration` 으로 분리 실행

.claude/settings.json

@@ -44,9 +44,9 @@
       "Bash(find:*)",
       "Bash(grep:*)",
       "Bash(ls:*)",
-      "Bash(./gradlew compileJava:*)",
-      "Bash(./gradlew build -x test:*)",
-      "Bash(./gradlew test:*)"
+      "Bash(./backend/gradlew -p backend compileJava:*)",
+      "Bash(./backend/gradlew -p backend build -x test:*)",
+      "Bash(./backend/gradlew -p backend test:*)"
     ]
   }
 }

.coderabbit.yaml

@@ -12,9 +12,9 @@ reviews:
     enabled: true
     drafts: false
   path_instructions:
-    - path: "src/main/java/**/*.java"
+    - path: "backend/src/main/java/**/*.java"
       instructions: "SOLID 원칙, 스프링 어노테이션, 의존성 주입 패턴, 예외 처리에 중점을 둔다"
-    - path: "src/test/**/*.java"
+    - path: "backend/src/test/**/*.java"
       instructions: "테스트 커버리지, 스프링 테스트 어노테이션, mock 사용법, 네이밍 규칙을 확인한다"
     - path: "**/*.{yml,yaml,properties}"
       instructions: "스프링 설정, 보안 설정, DB 연결, 환경 설정을 검증한다"

.gitattributes

@@ -1,3 +1,3 @@
-/gradlew text eol=lf
+/backend/gradlew text eol=lf
 *.bat text eol=crlf
 *.jar binary

AGENTS.md

@@ -42,7 +42,7 @@ Don't assume. Don't hide confusion. Surface tradeoffs.
 
 ### 🔵 작업 직전 항상
 - 프로젝트 구조 → 이 파일 (AGENTS.md)
-- 도메인 목록 → `src/main/java/com/opensource/docgrid/domain/`
+- 도메인 목록 → `backend/src/main/java/com/opensource/docgrid/domain/`
 
 ### 🟢 상황별 룰 (`.Codex/rules/`) — 자동 로드됨
 - Java 코드 작성 시 → `code_style.md`
@@ -67,7 +67,7 @@ Don't assume. Don't hide confusion. Surface tradeoffs.
 ## 프로젝트 구조
 
 ```
-src/main/java/com/opensource/docgrid/
+backend/src/main/java/com/opensource/docgrid/
 ├── global/
 │   ├── common/       # 공통 응답 (ApiResponse, ErrorResponse, BaseEntity)
 │   ├── config/       # 설정 (SecurityConfig, CorsConfig, SwaggerConfig)
@@ -90,10 +90,10 @@ src/main/java/com/opensource/docgrid/
 ## 주요 명령어
 
 ```bash
-./gradlew build
-./gradlew clean build
-./gradlew build -x test
-./gradlew test
+./backend/gradlew -p backend build
+./backend/gradlew -p backend clean build
+./backend/gradlew -p backend build -x test
+./backend/gradlew -p backend test
 ```
 
 ---

CLAUDE.md

@@ -28,7 +28,7 @@ Don't assume. Don't hide confusion. Surface tradeoffs.
 
 ### 🔵 작업 직전 항상
 - 프로젝트 구조 → 이 파일 (CLAUDE.md)
-- 도메인 목록 → `src/main/java/com/opensource/docgrid/domain/`
+- 도메인 목록 → `backend/src/main/java/com/opensource/docgrid/domain/`
 
 ### 🟢 상황별 룰 (`.claude/rules/`) — 자동 로드됨
 - 항상 로드 → `git-conventions.md` (브랜치·커밋·환경설정)
@@ -58,7 +58,7 @@ Don't assume. Don't hide confusion. Surface tradeoffs.
 ## 프로젝트 구조
 
 ```
-src/main/java/com/opensource/docgrid/
+backend/src/main/java/com/opensource/docgrid/
 ├── global/
 │   ├── common/       # 공통 응답 (ApiResponse, ErrorResponse, BaseEntity)
 │   ├── config/       # 설정 (SecurityConfig, CorsConfig, SwaggerConfig)
@@ -87,10 +87,10 @@ docs/
 ## 주요 명령어
 
 ```bash
-./gradlew build
-./gradlew clean build
-./gradlew build -x test
-./gradlew test
+./backend/gradlew -p backend build
+./backend/gradlew -p backend clean build
+./backend/gradlew -p backend build -x test
+./backend/gradlew -p backend test
 ```
 
 ---

README.md

@@ -1,53 +1,51 @@
-# DocGrid Backend
+# DocGrid
 
-## Local DB
+DocGrid는 문서 업로드·인덱싱·검색과 웹 인터페이스를 하나의 저장소에서 관리하는 모노레포입니다.
 
-로컬 개발 DB는 Docker Compose로 실행합니다. 기본 이미지는 PostgreSQL 17과 pgvector 0.8.1을
-함께 제공하는 `pgvector/pgvector:0.8.1-pg17`입니다.
+## 저장소 구조
+
+```text
+.
+├── backend/          # Spring Boot API와 임베딩 서버
+├── frontend/         # DocGrid 웹 애플리케이션
+├── docs/             # 설계 문서와 실행된 테스트 결과
+├── docker/           # 로컬 인프라 초기화 파일
+├── scripts/          # 프로젝트 공용 검증·보고 스크립트
+└── docker-compose.yml
+```
+
+## 빠른 시작
+
+### 로컬 인프라
 
 ```bash
 cp .env.example .env
 docker compose pull postgres
 docker compose up -d --wait --wait-timeout 60 postgres
-docker compose ps postgres
-./gradlew bootRun --args='--spring.profiles.active=local'
 ```
 
-`docker compose up --wait`가 PostgreSQL의 `healthy` 상태를 확인한 뒤에만 Application을
-기동한다.
-
-DB 기본 접속 정보는 `localhost:55432`, database `app`, user `app`입니다. 로컬 기본
-`DB_SSLMODE`는 `disable`이며 실제 비밀번호와 운영 접속정보는 환경변수로 주입합니다.
+### 백엔드
 
-PostgreSQL 17은 `docgrid_postgres17_data` 전용 볼륨을 사용합니다. 기존 PostgreSQL 14
-`opensql_data` 볼륨을 재사용하거나 자동 삭제하지 않습니다.
+```bash
+./backend/gradlew -p backend bootRun --args='--spring.profiles.active=local'
+```
 
-자세한 내용은 [docs/local-db.md](docs/local-db.md)를 참고하세요.
+자세한 백엔드 실행 방법은 [backend/README.md](backend/README.md)를 참고하세요.
 
-## 임베딩 서버
+### 프론트엔드
 
-문서 청크/질의를 벡터로 변환하는 FastAPI + sentence-transformers 서버입니다. 이미지가 자체 빌드 대상이라 최초 1회 build가 필요합니다.
+Node.js 22.13.0 이상이 필요합니다.
 
 ```bash
-docker compose build embedding-server
-docker compose up -d embedding-server
+npm --prefix frontend install
+npm --prefix frontend run dev
 ```
 
-- 첫 실행 시 `BAAI/bge-m3` 모델 다운로드로 약 10~15분 소요됩니다 (약 3GB).
-- `docker logs -f docgrid-embedding`으로 진행 상태를 확인할 수 있습니다.
-- 모델 로딩이 끝나기 전까지 `GET /health`는 503을 반환합니다. 200이 될 때까지 대기 후 사용하세요.
-- 기본 접속 정보는 `http://localhost:8000`이며, Spring Boot에서는 `EMBEDDING_SERVER_URL` 환경변수로 오버라이드할 수 있습니다.
+자세한 프론트엔드 실행 방법은 [frontend/README.md](frontend/README.md)를 참고하세요.
 
-## Ollama (RAG LLM 서버)
-
-RAG 답변 생성에 사용하는 로컬 LLM(`qwen2.5:3b`) 서버입니다. 공식 이미지를 그대로 사용하므로 별도 build 없이 실행만 하면 됩니다.
+## 검증
 
 ```bash
-docker compose up -d ollama
-docker compose exec ollama ollama pull qwen2.5:3b
-docker compose exec ollama ollama run qwen2.5:3b "안녕"
+./backend/gradlew -p backend test
+npm --prefix frontend test
 ```
-
-- `pull`은 최초 1회만 필요합니다 (약 2GB, `ollama-data` 볼륨에 캐시되어 이후 재구동 시 재다운로드하지 않습니다).
-- 정상 응답이 텍스트로 출력되면 준비 완료입니다.
-- 기본 접속 정보는 `http://localhost:11434`이며, Spring Boot에서는 `OLLAMA_SERVER_URL` 환경변수로 오버라이드할 수 있습니다.

backend/README.md

@@ -0,0 +1,55 @@
+# DocGrid Backend
+
+Spring Boot 백엔드와 문서 임베딩 서버는 `backend/`에서 관리합니다. 아래 명령은 저장소 루트에서 실행합니다.
+
+## Local DB
+
+로컬 개발 DB는 Docker Compose로 실행합니다. 기본 이미지는 PostgreSQL 17과 pgvector 0.8.1을
+함께 제공하는 `pgvector/pgvector:0.8.1-pg17`입니다.
+
+```bash
+cp .env.example .env
+docker compose pull postgres
+docker compose up -d --wait --wait-timeout 60 postgres
+docker compose ps postgres
+./backend/gradlew -p backend bootRun --args='--spring.profiles.active=local'
+```
+
+`docker compose up --wait`가 PostgreSQL의 `healthy` 상태를 확인한 뒤에만 Application을
+기동한다.
+
+DB 기본 접속 정보는 `localhost:55432`, database `app`, user `app`입니다. 로컬 기본
+`DB_SSLMODE`는 `disable`이며 실제 비밀번호와 운영 접속정보는 환경변수로 주입합니다.
+
+PostgreSQL 17은 `docgrid_postgres17_data` 전용 볼륨을 사용합니다. 기존 PostgreSQL 14
+`opensql_data` 볼륨을 재사용하거나 자동 삭제하지 않습니다.
+
+자세한 내용은 [로컬 DB 실행 문서](../docs/local-db.md)를 참고하세요.
+
+## 임베딩 서버
+
+문서 청크/질의를 벡터로 변환하는 FastAPI + sentence-transformers 서버입니다. 이미지가 자체 빌드 대상이라 최초 1회 build가 필요합니다.
+
+```bash
+docker compose build embedding-server
+docker compose up -d embedding-server
+```
+
+- 첫 실행 시 `BAAI/bge-m3` 모델 다운로드로 약 10~15분 소요됩니다 (약 3GB).
+- `docker logs -f docgrid-embedding`으로 진행 상태를 확인할 수 있습니다.
+- 모델 로딩이 끝나기 전까지 `GET /health`는 503을 반환합니다. 200이 될 때까지 대기 후 사용하세요.
+- 기본 접속 정보는 `http://localhost:8000`이며, Spring Boot에서는 `EMBEDDING_SERVER_URL` 환경변수로 오버라이드할 수 있습니다.
+
+## Ollama (RAG LLM 서버)
+
+RAG 답변 생성에 사용하는 로컬 LLM(`qwen2.5:3b`) 서버입니다. 공식 이미지를 그대로 사용하므로 별도 build 없이 실행만 하면 됩니다.
+
+```bash
+docker compose up -d ollama
+docker compose exec ollama ollama pull qwen2.5:3b
+docker compose exec ollama ollama run qwen2.5:3b "안녕"
+```
+
+- `pull`은 최초 1회만 필요합니다 (약 2GB, `ollama-data` 볼륨에 캐시되어 이후 재구동 시 재다운로드하지 않습니다).
+- 정상 응답이 텍스트로 출력되면 준비 완료입니다.
+- 기본 접속 정보는 `http://localhost:11434`이며, Spring Boot에서는 `OLLAMA_SERVER_URL` 환경변수로 오버라이드할 수 있습니다.

build.gradle → backend/build.gradle

@@ -58,6 +58,11 @@ tasks.named('test') {
 	}
 }
 
+tasks.named('bootRun') {
+	// 모노레포 루트의 .env와 Docker Compose 설정을 기존 로컬 실행 방식 그대로 사용한다.
+	workingDir rootProject.projectDir.parentFile
+}
+
 tasks.register('localE2eTest', Test) {
 	group = 'verification'
 	description = '실제 PostgreSQL, MinIO와 BGE-M3를 연결한 로컬 문서 인덱싱 E2E를 실행합니다.'