이제부터는 실제 구현을 위한 바닥을 깔아야 합니다. 앞 장까지에서 우리는 서비스 기획, DDD 모델링, 화면 구조를 정리했습니다. 하지만 이 설계를 코드로 옮기려면 먼저 저장소 구조를 고정해야 합니다. 저장소 구조는 단순 취향 문제가 아닙니다. 어떤 폴더에 무엇을 두는지에 따라 협업 방식, 공통 코드 재사용, 테스트 경로, 실행 스크립트, 배포 기준이 모두 달라집니다.
초기 구조를 대충 잡으면 나중에 거의 반드시 같은 문제가 생깁니다.
이번 페이지의 목적은 이 혼선을 막는 것입니다. 실전형 풀스택 교재답게, 이커머스 서비스 개발에 필요한 폴더 경계와 책임을 먼저 고정합니다.
이번 교재는 storefront, admin, backend, AI 상담 챗봇, 문서, 실행 스크립트가 모두 함께 움직이는 프로젝트입니다. 이런 구조를 여러 레포로 나누면 각 레포의 변경 속도와 문맥이 쉽게 어긋납니다.
예를 들어:
모노레포를 쓰면 최소한 아래 장점이 생깁니다.
즉 이번 교재에서 모노레포는 유행이 아니라, 학습과 구현의 정합성을 맞추기 위한 현실적인 선택입니다.
이 페이지를 읽고 나면 아래 항목이 정리되어 있어야 합니다.
이 기준이 잡혀야 다음 페이지의 로컬 개발환경과 compose 구성이 자연스럽게 이어집니다.
이번 교재는 아래와 같은 형태로 저장소를 잡는 것이 자연스럽습니다.
lecture/
client/
storefront/
admin/
server/
packages/
scripts/
sdd/
compose.yml
README.md
AGENTS.md
이 구조는 아주 단순하지만, 실전 개발에 필요한 축을 모두 갖습니다.
client/storefront: 구매자용 프론트엔드client/admin: 운영자용 프론트엔드server: 백엔드와 도메인 로직packages: 공통 계약이나 유틸scripts: 실행/초기화/배포 보조 스크립트sdd: 기획/설계/검증 기록client/storefront와 client/admin을 분리하는가운영자 화면과 구매자 화면은 단순히 메뉴만 다른 것이 아닙니다. 라우트, 레이아웃, 인증, 상태 우선순위가 모두 다릅니다. 그래서 같은 React 앱 안에서 모든 것을 억지로 해결하려고 하면 다음 문제가 생기기 쉽습니다.
따라서 이번 교재에서는 storefront와 admin을 명시적으로 분리하는 편이 좋습니다.
이 분리는 앞 장의 화면 기획 결과와도 정확히 맞아야 합니다.
server는 별도 루트로 두는가백엔드는 단순 API 파일 모음이 아니라 도메인 규칙, 애플리케이션 서비스, 영속화, 테스트가 같이 존재하는 공간입니다. 그래서 프론트와는 별도 루트 경계가 있는 편이 이해가 쉽습니다.
권장 구조는 대략 아래처럼 생각할 수 있습니다.
server/
api/
domain/
application/
infra/
tests/
이번 교재에서는 구현이 너무 무거워지지 않도록 단순화할 수 있지만, 최소한 아래 사고는 유지해야 합니다.
api: 라우터/핸들러domain: 애그리거트, 엔티티, 값 객체, 도메인 규칙application: 유스케이스 오케스트레이션infra: DB, 외부 연동, 저장소 구현tests: 기능/도메인 검증packages는 왜 필요한가모노레포를 쓰면서 가장 쉽게 놓치는 것이 공통 코드의 위치입니다. 공통 코드가 애매하면 다음처럼 됩니다.
그래서 공통으로 재사용될 수 있는 것은 packages로 분리하는 편이 좋습니다.
모든 것을 packages에 몰아넣으라는 뜻은 아닙니다. 진짜로 여러 앱이 같이 쓰는 것만 분리해야 합니다.
scripts는 어디까지를 담당하는가실전 저장소가 지저분해지는 가장 쉬운 방법은 실행 스크립트를 루트 여기저기에 흩뿌리는 것입니다. 이를 막기 위해 스크립트는 별도 경계를 두는 편이 좋습니다.
scripts에 두기 좋은 것scripts에 두지 말아야 할 것즉 scripts는 개발과 운영을 돕는 자동화 도구의 위치입니다.
sdd는 왜 코드와 같은 저장소에 있어야 하는가이번 교재는 단순 튜토리얼이 아니라, 설계와 구현과 검증이 연결되는 교재입니다. 그래서 sdd는 별도 문서 보관함이 아니라 구현의 근거가 되는 기록 공간입니다.
sdd에 남겨야 하는 것이것을 코드와 다른 저장소에 두면 변경이 쉽게 어긋납니다. 같은 레포 안에 있으면 적어도 구현을 바꿀 때 설계도 함께 볼 가능성이 높아집니다.
루트에는 아래 정도 파일이 있으면 충분합니다.
README.mdAGENTS.mdcompose.yml이 세 파일만 잘 잡혀도 새로 들어온 사람이 저장소를 훨씬 빨리 이해할 수 있습니다.
기능을 어디에 넣을지 고민될 때는 아래 질문으로 판단하면 됩니다.
client/storefrontclient/adminpackagesserverscripts이 기준이 있으면 새 기능을 어디에 넣을지 덜 헷갈립니다.
아래 구조는 처음에는 편해 보여도 금방 문제를 만듭니다.
src/
api/
admin/
storefront/
utils/
scripts/
처음에는 간단하지만, 앱 경계와 공통 코드 경계가 흐려집니다.
이번 교재는 풀스택 흐름을 같이 따라가는 것이 핵심이라, 이 방식은 학습 효과를 떨어뜨립니다.
이 방식은 다른 앱이 복사본을 만들게 하고 결국 계약 불일치를 만듭니다.
이번 교재를 따라 하는 학습자는 최소한 아래 구조를 목표로 잡으면 충분합니다.
lecture/
client/
storefront/
admin/
server/
packages/
scripts/
sdd/
compose.yml
README.md
필요하다면 이후에 아래를 추가할 수 있습니다.
.github/workflows/docs/ 대신 sdd 유지assets/ 또는 images/storefront 안에 먼저 만들고 나중에 복사한다이 다섯 가지 실수는 뒤 장의 구현 속도와 이해도를 크게 떨어뜨립니다.
이 페이지에서 우리는 실전형 이커머스 교재에 맞는 모노레포 구조를 정리했습니다. client/storefront, client/admin, server, packages, scripts, sdd가 각각 어떤 책임을 가져야 하는지 고정했고, 이후 기능을 어디에 넣어야 할지도 기준을 세웠습니다. 다음 페이지에서는 이 구조 위에서 실제로 서비스를 함께 띄우기 위해 로컬 개발환경, compose, env 구성을 정리합니다.
다음 페이지에서는 여러 앱과 백엔드를 한 번에 돌릴 수 있도록 로컬 개발환경, compose, 환경변수 구조를 설계합니다.