06 · Developer Guide
저장소 구조Repository Anatomy
새로 합류한 개발자가 코드 구조를 쉽게 이해할 수 있도록 정리한 디렉터리 지도입니다.
라우트 그룹과 데이터 모듈 패턴이 핵심입니다.
디렉터리 트리
text
foundry-pcl/
├── app/
│ ├── (docs)/ ← 디자인 시스템 문서 (이 페이지가 속한 곳)
│ │ ├── about/ · 시스템 소개·원칙·라이선스
│ │ ├── components/ · 60+ UI 컴포넌트 페이지
│ │ ├── design-style/ · 색·타이포·아이콘·토큰
│ │ ├── engineering/ · 코드 레시피·워크플로 (신설)
│ │ ├── getting-started/ · 디자이너·개발자·TF 가이드
│ │ ├── news/ · 변경 이력
│ │ ├── patterns/ · 기본 UI 패턴
│ │ ├── service-patterns/ · 서비스 여정 패턴
│ │ └── docs/[[...slug]]/ · PRD·IA·회의록 정적 문서
│ │
│ ├── (site)/ ← PCL 시안 사이트
│ │ └── site/
│ │ ├── page.tsx · 홈
│ │ ├── community/ · 공동체 (about·history·staff·…)
│ │ ├── worship/ · 예배 (sunday·dawn·wednesday·…)
│ │ ├── nurture/ · 양육 (qt·parish·courses·…)
│ │ ├── next-gen/ · 다음 세대
│ │ ├── mission/ · 선교와 섬김
│ │ ├── yard/ · 교회 마당 (news·bulletin·…)
│ │ └── auth/ · 로그인·회원가입
│ │
│ ├── layout.tsx
│ └── globals.css · Tailwind v4 @theme 토큰 정의
│
├── components/
│ ├── ui/ · 디자인 시스템 원자 (Button·Card·Input 등)
│ ├── docs/ · 문서 페이지 전용 위젯
│ │ (DocPage·ComponentPreview·Callout·PrevNext)
│ ├── preview/ · PCL 시안 위젯
│ │ (SermonCard·PhotoGallery·CounselForm 등)
│ └── site/ · 사이트 공통 (Header·Footer·Sidebar)
│
├── lib/
│ ├── docs/
│ │ └── nav.ts · 단일 NAV 소스 — 사이드바·브레드크럼·prev/next
│ ├── preview/ · PCL 시안 데이터 모듈
│ │ ├── news.ts · 알림·새소식 게시물
│ │ ├── bulletin.ts · 주보 호별
│ │ ├── hamjul.ts · 함즐함울 호별
│ │ ├── qt.ts · 큐티 일별
│ │ └── staff.ts · 교역자·장로·직원
│ └── utils/
│
└── public/
├── brand/ · 로고·CI
├── hero/ · 홈 슬라이드
├── jubo/ · 주보 이미지
├── hamjul/ · 함즐함울 이미지
├── qt/ · 큐티 이미지
└── news/ · 새소식 게시물 갤러리폴더별 책임
app/(docs)/문서 사이트
60+ UI 컴포넌트·패턴·서비스 패턴·개발 가이드 레시피·PRD를 라우트별로 묶음. layout이 사이드바 + 컨텐츠 2분할.
app/(site)/site/PCL 시안
117개 정적 페이지로 PCL 홈페이지 시안을 만든다. (docs) 와 라우트 그룹이 분리돼 layout이 다름.
components/ui/디자인 시스템 원자
Button·Card·Input 같은 재사용 가능한 UI 컴포넌트. 외부 프로젝트에 그대로 복사 가능.
components/preview/PCL 시안 위젯
PageHeader·SermonCard·PhotoGallery·CounselForm 등 시안 페이지 전용 컴포넌트. ui/와 달리 도메인 지식 포함.
components/docs/문서 페이지 위젯
DocPage 래퍼·ComponentPreview(shiki)·Callout·OnThisPage·PrevNext. (docs) 페이지에서만 사용.
components/site/사이트 공통
PreviewHeader·PreviewFooter·SiteSidebar·MegaPanel — 시안과 문서 양쪽에서 공유.
lib/docs/nav.ts단일 NAV 소스
사이드바 아코디언·헤더 드롭다운·브레드크럼·prev/next·검색 인덱스가 모두 이 한 파일에서 파생.
lib/preview/*.ts시안 데이터 모듈
외부 사이트에서 가져온 게시물·인물 데이터를 정적 배열로. 인덱스·상세 페이지가 같은 모듈을 import.
public/{news,jubo,hamjul,qt}/자체호스팅 자산
pcltv.org에서 가져와 자체 호스팅한 이미지. 게시물 ID별 하위 폴더로 정리.
라우트 그룹 컨벤션
(docs)는 시스템 사이드바·문서용 layout. URL은/components/button처럼 그룹 이름이 빠진 평면.(site)는 PCL 시안 layout. URL은/site/community/about형태로 항상/site시작.- 두 그룹은 layout과 컴포넌트 세트가 완전히 다르므로 서로의 컴포넌트를 import하지 않습니다.
데이터 흐름 — 게시판 페이지가 동작하는 길
- 외부에서 가져온 자산을
public/{news,hamjul,…}/에 자체 호스팅 lib/preview/{news,hamjul,…}.ts에 경로 + 본문을 배열로 등록- 인덱스 페이지(
app/(site)/site/yard/news/page.tsx)는 배열을 읽어 카드 그리드 렌더 - 상세 페이지(
[id]/page.tsx)는generateStaticParams로 모든 id를 정적 빌드, 클라이언트에서는PhotoGallery등 클라이언트 컴포넌트가 라이트박스 동작