[block-server] 프로젝트 구조

Structure

• Notion 스타일의 문서 계층과 블록 트리를 다루는 백엔드 서비스이며, Spring Boot 기반 Gradle 멀티모듈 구조로 책임을 분리한 것이 핵심!

📦 Block-server
├─ AGENTS.md
├─ README.md
├─ docker
│  ├─ Dockerfile
│  ├─ docker-compose.yml
│  └─ docker.sh
├─ docs
│  ├─ REQUIREMENTS.md
│  ├─ decisions
│  │  ├─ 000-adr-template.md
│  │  └─ README.md
│  ├─ discussions
│  │  ├─ 000-strategy-review-template.md
│  │  └─ README.md
│  ├─ roadmap
│  │  ├─ README.md
│  │  └─ v2
│  │     └─ blocks
│  │        ├─ block-delete.md
│  │        └─ block-restore.md
│  └─ runbook
│     └─ DEBUG.md
├─ documents-api
│  ├─ build.gradle
│  └─ src
│     └─ main
│        └─ java
│           └─ com
│              └─ documents
│                 ├─ api
│                 │  ├─ block
│                 │  │  ├─ BlockApiMapper.java
│                 │  │  ├─ BlockController.java
│                 │  │  ├─ dto
│                 │  │  │  ├─ BlockResponse.java
│                 │  │  │  ├─ CreateBlockRequest.java
│                 │  │  │  └─ UpdateBlockRequest.java
│                 │  │  ├─ support
│                 │  │  │  └─ BlockJsonCodec.java
│                 │  │  └─ validation
│                 │  │     ├─ BlockContentValidator.java
│                 │  │     └─ ValidBlockContent.java
│                 │  ├─ code
│                 │  │  ├─ ErrorCode.java
│                 │  │  └─ SuccessCode.java
│                 │  ├─ document
│                 │  │  ├─ DocumentApiMapper.java
│                 │  │  ├─ DocumentController.java
│                 │  │  ├─ dto
│                 │  │  │  ├─ CreateDocumentRequest.java
│                 │  │  │  ├─ DocumentResponse.java
│                 │  │  │  ├─ MoveDocumentRequest.java
│                 │  │  │  └─ UpdateDocumentRequest.java
│                 │  │  ├─ support
│                 │  │  │  └─ DocumentJsonCodec.java
│                 │  │  └─ validation
│                 │  │     ├─ DocumentMetaValidator.java
│                 │  │     └─ ValidDocumentMeta.java
│                 │  ├─ dto
│                 │  │  ├─ BaseResponse.java
│                 │  │  └─ GlobalResponse.java
│                 │  ├─ exception
│                 │  │  ├─ GlobalException.java
│                 │  │  └─ GlobalExceptionHandler.java
│                 │  └─ workspace
│                 │     ├─ WorkspaceController.java
│                 │     └─ dto
│                 │        ├─ CreateWorkspaceRequest.java
│                 │        └─ WorkspaceResponse.java
│                 └─ common
│                    └─ SwaggerConfig.java
├─ documents-boot
│  ├─ build.gradle
│  └─ src
│     └─ main
│        └─ java
│           └─ com
│              └─ documents
│                 └─ DemoApplication.java
├─ documents-core
│  ├─ build.gradle
│  └─ src
│     └─ main
│        └─ java
│           └─ com
│              └─ documents
│                 ├─ common
│                 │  └─ BaseEntity.java
│                 ├─ domain
│                 │  ├─ Block.java
│                 │  ├─ BlockType.java
│                 │  ├─ Document.java
│                 │  └─ Workspace.java
│                 ├─ exception
│                 │  ├─ BusinessErrorCode.java
│                 │  └─ BusinessException.java
│                 └─ service
│                    ├─ BlockService.java
│                    ├─ DocumentService.java
│                    └─ WorkspaceService.java
├─ documents-infrastructur
│  └─ src
│     └─ main
│        └─ java
│           └─ com
│              └─ documents
│                 ├─ repository
│                 │  ├─ BlockRepository.java
│                 │  ├─ DocumentRepository.java
│                 │  └─ WorkspaceRepository.java
│                 ├─ service
│                 │  ├─ BlockServiceImpl.java
│                 │  ├─ DocumentServiceImpl.java
│                 │  └─ WorkspaceServiceImpl.java
│                 └─ support
│                    ├─ OrderedSortKeyGenerator.java
│                    └─ TextNormalizer.java
└─ prompts
   ├─ 0-initial-setup.md
   ├─ README.md
   ├─ explainer
   └─ plan

---

Explains

💡documents-boot

• 애플리케이션 실행 진입점, 프로필/환경설정, 패키징 담당
• `DemoApplication.java`가 위치하며, 실제 서버 실행과 설정 로딩을 담당한다.
• 즉, 다른 모듈이 기능을 제공하는 라이브러리라면 `documents-boot`는 그것들을 조립해서 실행 가능한 애플리케이션으로 만드는 역할을 한다.

💡documents-api

• 외부 요청을 직접 받는 계층이다.
• 이 모듈에는 다음과 같은 요소가 들어 있다.
  - `Controller`: 문서, 블록, 워크스페이스 API 엔드포인트
  - `dto`: 요청/응답 객체
  - `validation`: 요청값 검증 로직
  - `support`: JSON 변환 보조 로직
  - `code`, `exception`: 공통 응답 코드와 예외 처리
  - `SwaggerConfig`: API 문서화 설정
• 즉, HTTP 요청을 받아 검증하고, 도메인 계층에 작업을 위임한 뒤, 다시 응답 형식으로 변환하는 역할을 맡는다.

💡documents-core

• 서비스의 중심 규칙을 담는 계층이다.
• 여기에는 다음이 위치한다.
  - `domain`: `Document`, `Block`, `Workspace` 같은 핵심 엔티티
  - `service`: 도메인 서비스 인터페이스
  - `exception`: 비즈니스 예외와 에러 코드
  - `common`: 공통 엔티티 기반 클래스
• 중요한 점은, 이 계층은 "무엇을 해야 하는가"를 정의한다는 것이다.  
• 구체적으로 어떻게 저장하는지는 여기서 다루지 않고, 서비스 계약과 도메인 모델 중심으로 구조를 잡고 있다.

💡documents-infrastructure

• 실제 구현을 담당한다.
• 이 모듈에는 다음이 있다.
  - `repository`: JPA Repository
  - `service`: `documents-core`의 서비스 인터페이스 구현체
  - `support`: 정렬 키 생성기, 문자열 정규화 같은 보조 유틸리티
• 예를 들어 문서 이동, 블록 생성, soft delete 같은 실제 비즈니스 처리는 이 계층의 `ServiceImpl`에서 수행된다.  
• 즉, `core`가 계약이라면 `infrastructure`는 그 계약의 실행체다.

💡문서화와 운영 보조 구조

• 루트에는 코드 외에도 협업과 기록을 위한 디렉터리가 따로 존재한다.
  - `docs/REQUIREMENTS.md`: 현재 유효한 요구사항 기준서
  - `docs/decisions`: 채택된 기술 결정(ADR)
  - `docs/discussions`: 전략 검토, 비교, 회의 메모
  - `docs/roadmap`: 후속 버전 확장 계획
  - `docs/runbook`: 재현 가능한 디버깅 절차
  - `prompts`: AI 작업 로그와 설명 문서
• 이 구조는 단순히 코드를 작성하는 데서 끝나지 않고,  "왜 이렇게 만들었는지", "무엇을 결정했는지", "다음엔 무엇을 할지"까지 함께 관리하려는 의도가 반영된 설계다.

💡실행 환경

• 루트의 `docker/` 디렉터리는 로컬 실행 환경을 담당한다.
  - `Dockerfile`
  - `docker-compose.yml`
  - `docker.sh`
• 즉, 애플리케이션과 DB를 포함한 실행 환경을 빠르게 재현할 수 있도록 준비된 구조다.
• `docker-compose.yml`을 활용해 애플리케이션과 MySQL 같은 실행 의존성을 함께 올릴 수 있도록 구성해, 로컬 개발 환경을 빠르게 재현할 수 있게 했다.

---

Github Repo

https://github.com/jho951/Block-server

GitHub - jho951/Block-server: server drawer