기업 웹사이트 템플릿 시스템 아키텍트 프롬프트

## 1. 프로젝트 포지셔닝 이 템플릿 시스템은 기업 웹사이트를 반복적으로 구축하기 위한 재사용 가능한 구조적 골격입니다. 단일 회사 사이트가 아니라, 브랜드 요소 교체와 기능 모듈 확장을 통해 다양한 산업에 적용할 수 있는 표준화된 시스템입니다. 해결하는 문제: - 매번 처음부터 웹사이트를 개발할 때 발생하는 반복 작업 비용 - 브랜드별로 구조가 제각각이 되어 유지보수가 어려워지는 문제 - 기능 추가 시 기존 구조와 충돌하는 문제 - 프론트엔드와 백엔드 간 협업 시 표준이 없어 생기는 비효율 적합한 기업 유형: - 기술 기업, 리테일, 서비스 업종, Web3/블록체인, SaaS, 브랜드 쇼케이스 적합하지 않은 시나리오: - 극도로 독특한 비즈니스 로직이 필요한 맞춤형 플랫폼 - 실시간 데이터 처리나 복잡한 사용자 상호작용이 핵심인 서비스 - 법적/규제 요구사항이 매우 특수한 산업 핵심 가치: - 구조적 골격을 한 번 설계하면 이후 프로젝트에서 개발 시간을 60~70% 단축 - 브랜드 교체를 설정 파일과 테마 교체만으로 완료 - 기능 모듈을 켜고 끄는 방식으로 프로젝트 범위를 유연하게 조절 매번 개별 개발하는 것보다 효율적인 이유: - 공통 구조, 컴포넌트, API 패턴, 관리 체계를 재사용 - 프로젝트별로 새로 설계하고 검증하는 시간을 제거 - 유지보수 인력이 시스템 구조를 한 번만 학습하면 모든 프로젝트에 적용 가능 --- ## 2. 알려진 정보와 가정 ### 알려진 정보 - 재사용 가능한 기업 웹사이트 템플릿 시스템을 구축하려는 목적 - 기술 기업, 리테일, 서비스 업종, Web3/블록체인, SaaS, 브랜드 쇼케이스에 활용 예정 - 통일된 구조, 브랜드 교체 용이성, 기능 모듈 확장성, 장기 유지보수성을 핵심 요구사항으로 제시 ### 가정 - 가정 1: 초기 MVP는 단일 브랜드로 시작하되, 시스템 설계는 다중 브랜드 확장을 전제로 함 - 가정 2: 각 프로젝트는 정적 콘텐츠 중심의 기업 소개, 제품/서비스 안내, 문의 기능이 기본 범위 - 가정 3: 백엔드는 콘텐츠 관리, 문의 폼 처리, 설정 관리가 주요 역할이며, 복잡한 비즈니스 로직은 프로젝트별 확장으로 처리 - 가정 4: 개발 팀 규모는 프론트엔드 1~2명, 백엔드 1명 수준 - 가정 5: 배포 환경은 클라우드 기반 컨테이너 배포를 기본으로 함 --- ## 3. 템플릿 시스템 설계 원칙 **통일 구조 원칙** 모든 프로젝트가 동일한 페이지 계층과 컴포넌트 구조를 사용한다. 이 원칙이 없으면 프로젝트마다 구조가 달라져 재사용이 불가능하다. **설정 가능성 원칙** 브랜드 요소와 기능 토글은 코드 수정 없이 설정으로 변경 가능해야 한다. 이 원칙이 없으면 브랜드 교체 시 개발자 개입이 필요하다. **확장성 원칙** 새 기능은 기존 구조를 수정하지 않고 추가하는 방식으로 구현한다. 이 원칙이 없으면 기능 추가 시 기존 코드와 충돌한다. **브랜드 분리 원칙** 브랜드 관련 요소는 시스템 코어와 완전히 분리한다. 이 원칙이 없으면 브랜드 교체 시 코어 로직까지 수정해야 한다. **프론트엔드-백엔드 분리 원칙** 프론트엔드와 백엔드는 API로만 통신한다. 이 원칙이 없으면 한쪽 변경이 다른 쪽에 직접 영향을 준다. **유지보수 비용 통제 원칙** 모든 코드는 일관된 규칙을 따르며, 문서화가 필수다. 이 원칙이 없으면 시간이 지날수록 유지보수 비용이 기하급수적으로 증가한다. **일관된 사용자 경험 원칙** 모든 프로젝트에서 동일한 UI 패턴과 인터랙션 규칙을 사용한다. 이 원칙이 없으면 사용자가 각 사이트에서 혼란을 겪는다. --- ## 4. 프론트엔드 아키텍처 설계 ### 4.1 페이지 계층 기본 페이지: - 홈 - 회사 소개 - 제품/서비스 - 문의 - 블로그/뉴스 - FAQ - 채용/팀 소개 확장 페이지: - 커스텀 랜딩 페이지 - 고객 사례 - 파트너 소개 - 미디어/보도자료 페이지 계층은 고정 구조로 설계하되, 각 페이지의 활성화 여부는 설정으로 제어한다. ### 4.2 컴포넌트 모듈 재사용 컴포넌트: - 헤더: 로고, 내비게이션, 언어 선택기, CTA 버튼 - 푸터: 회사 정보, 링크, 소셜 아이콘, 뉴스레터 - 배너: 히어로 섹션, 이미지 배경, 텍스트 오버레이 - 기능 소개: 아이콘 + 제목 + 설명 그리드 - CTA: 행동 유도 버튼 + 배경 이미지 - 고객 후기: 인용구 + 사진 + 회사명 - 폼: 문의 폼, 뉴스레터 폼, 콜백 요청 폼 - 카드: 제품 카드, 블로그 카드, 팀 카드 - FAQ: 아코디언 형태 - 모달/드로어/알림: 공통 UI 피드백 컴포넌트 각 컴포넌트는 props와 설정 데이터로만 동작하며, 내부 로직은 브랜드에 의존하지 않는다. ### 4.3 설정 가능 항목 - 로고: 이미지 파일 경로, 크기, 대체 텍스트 - 색상: 브랜드 프라이머리/세컨더리/액센트 색상, 배경색, 텍스트색 - 폰트: 본문/제목 폰트 패밀리, 크기, 굵기 - 버튼 스타일: 모양(둥근 모서리/직각), 색상, 호버 효과 - 이미지 자산: 배너, 배경, 제품 이미지 - 텍스트 콘텐츠: 모든 페이지의 문구 - 페이지 섹션 순서: 홈페이지 섹션 배열 순서 - 모듈 토글: 블로그, FAQ, 채용 등의 활성화/비활성화 - 다국어 콘텐츠: 언어별 텍스트 매핑 ### 4.4 반응형 디자인과 인터랙션 모바일 우선 전략: - 기본 스타일은 모바일 기준으로 작성 - 태블릿(768px)과 데스크톱(1024px 이상)은 미디어 쿼리로 확장 - 내비게이션은 모바일에서 햄버거 메뉴로 전환 로딩/빈/에러 상태: - 모든 데이터 요청에 로딩 스피너 표시 - 빈 상태는 안내 문구와 CTA 버튼 제공 - 에러 상태는 재시도 버튼과 에러 메시지 표시 일관성 유지: - 모든 상태 처리는 공통 훅/유틸리티로 통일 - 인터랙션 패턴은 컴포넌트 라이브러리로 강제 ### 4.5 권장 프론트엔드 기술 **Next.js를 권장한다.** 이유: - 서버 사이드 렌더링과 정적 생성을 기본 지원하여 SEO에 유리 - 파일 기반 라우팅으로 페이지 추가가 간단 - API 라우트를 제공하여 백엔드가 분리되어 있어도 프론트엔드 단독 배포 가능 - 이미지 최적화, 폰트 최적화 등 성능 기능이 내장됨 - React 생태계를 그대로 활용 가능 React 단독이나 Vue는 라우팅, SSR, 빌드 설정을 별도로 구성해야 하므로 템플릿 시스템에는 비효율적이다. HTML/CSS/JavaScript는 컴포넌트 재사용과 상태 관리가 어려워 제외한다. --- ## 5. 백엔드 아키텍처 설계 ### 5.1 백엔드 책임 - 설정 로딩: 브랜드 설정, 기능 토글, 다국어 설정을 제공 - 폼 처리: 문의 폼, 뉴스레터 폼의 수신 및 저장 - 사용자 데이터: 관리자 계정, 권한 관리 - 콘텐츠 관리: 블로그, FAQ, 제품 정보의 CRUD - 관리자 API: 관리 화면에서 사용하는 API - 권한 제어: 관리자/편집자/뷰어 권한 분리 - 서드파티 통합: 이메일 발송, CRM 연동, 결제 연동 - 로깅 및 모니터링: 요청 로그, 에러 추적 ### 5.2 기술 선택 권장 **Node.js + Express/NestJS를 권장한다.** 이유: - 프론트엔드와 동일한 언어(TypeScript)를 사용하여 협업 효율이 높음 - JSON 기반 API가 자연스럽게 설계됨 - npm 생태계가 가장 크고 성숙함 - 템플릿 프로젝트 간 코드 공유가 용이함 Python(Django/FastAPI)도 좋은 선택이지만, 프론트엔드와 언어가 달라 타입 공유와 협업 비용이 증가한다. 템플릿 시스템의 목적이 다중 프로젝트 재사용이므로, 프론트엔드와의 일관성이 더 중요하다. ### 5.3 API 설계 방식 공통 API 추상화: - `/api/config` - 브랜드 설정, 기능 토글 - `/api/content` - 페이지 콘텐츠 CRUD - `/api/forms` - 폼 제출 처리 - `/api/auth` - 인증 및 권한 - `/api/admin` - 관리 기능 비즈니스 특화 API 확장: - 프로젝트별로 `/api/custom` 접두어를 사용하여 별도 라우터로 추가 - 공통 API는 수정하지 않고, 확장 모듈로 추가 재사용 지원: - 모든 API는 버전을 명시(`/api/v1/...`) - 응답 형식을 통일: `{ success: boolean, data: any, error: string | null }` 비제어적 결합 방지: - 공통 API는 코어 모듈로 고정하고, 프로젝트별 요구사항은 확장 모듈로 처리 - 확장 모듈은 코어 API를 직접 수정하지 않고, 별도 라우터로 추가 ### 5.4 데이터 및 권한 설계 핵심 데이터 객체: - 사이트 설정: 브랜드명, 로고, 색상, 폰트, 기능 토글 - 페이지 콘텐츠: 페이지별 섹션 데이터, 텍스트, 이미지 - 폼 데이터: 제출된 문의, 뉴스레터 구독 - 사용자/관리자: 계정 정보, 역할, 권한 - 모듈 상태: 각 기능 모듈의 활성화 상태 - 다중 브랜드 설정 격리: 브랜드 ID로 모든 데이터를 구분 권한 설계: - 관리자: 전체 설정 및 콘텐츠 관리 - 편집자: 콘텐츠만 관리, 설정 변경 불가 - 뷰어: 읽기 전용 --- ## 6. 템플릿 커스터마이징 메커니즘 ### 6.1 브랜드 레벨 커스터마이징 - 회사명: 설정 파일의 `brand.name` 값 변경 - 로고: `brand.logo` 경로 변경 - 색상 팔레트: `brand.colors` 객체의 프라이머리/세컨더리/액센트 값 변경 - 폰트: `brand.fonts` 객체의 본문/제목 폰트 패밀리 변경 - 이미지 스타일: `brand.imageStyle` 설정으로 필터, 모서리 처리 방식 변경 - 브랜드 톤: `brand.tone` 설정으로 문구 스타일(전문적/친근한/혁신적)을 지정하고, 이에 맞는 기본 문구 템플릿 제공 ### 6.2 페이지 레벨 커스터마이징 - 페이지 수: `pages` 설정 배열에서 활성화할 페이지 지정 - 페이지 순서: `pages` 배열의 순서 변경 - 페이지 템플릿 재사용: 동일한 레이아웃을 여러 페이지에 적용 - 홈페이지 섹션 구성: `homepage.sections` 배열에서 섹션 순서와 활성화 여부 지정 - 콘텐츠 블록 추가/제거: 각 페이지에서 사용할 블록을 설정으로 지정 ### 6.3 기능 레벨 커스터마이징 - 문의 폼: `features.contactForm` 활성화/비활성화, 필드 구성 설정 - 제품 쇼케이스: `features.products` 활성화, 카테고리 구성 - 서비스 예약: `features.booking` 활성화, 예약 가능 시간 설정 - 블로그: `features.blog` 활성화, 카테고리 설정 - FAQ: `features.faq` 활성화, 질문/답변 데이터 - 관리자 패널: `features.admin` 활성화, 관리자 계정 수 - 다국어 지원: `features.i18n` 활성화, 지원 언어 목록 - SEO: `features.seo` 활성화, 메타데이터 설정 - 서드파티 통합: `features.integrations` 배열에서 활성화할 통합 모듈 지정 ### 6.4 설정 방법 권장 설정 파일(JSON/YAML): - 브랜드 기본 설정, 기능 토글, 페이지 구성 - 적합한 경우: 코드 배포와 함께 관리되는 정적 설정 CMS: - 블로그, 뉴스, 제품 정보, FAQ 콘텐츠 - 적합한 경우: 비개발자가 콘텐츠를 수정해야 하는 경우 데이터베이스: - 폼 제출 데이터, 사용자 계정, 권한 - 적합한 경우: 동적으로 생성되고 관리되어야 하는 데이터 관리 시스템: - 브랜드 설정 변경, 기능 토글, 콘텐츠 편집 - 적합한 경우: 개발자 없이 운영팀이 설정을 변경해야 하는 경우 --- ## 7. 다중 산업 적응 권장 ### 기술 기업 - 유지: 전체 구조, 컴포넌트, API 패턴 - 조정: 비주얼 - 모던하고 미니멀한 스타일, 블루/그레이 계열 색상 - 조정: 기능 - 제품 쇼케이스, 기술 블로그, 채용 페이지 강화 - 비용: 브랜드 설정과 콘텐츠 교체만으로 완료 ### 리테일 기업 - 유지: 전체 구조, 컴포넌트, API 패턴 - 조정: 비주얼 - 따뜻하고 친근한 스타일, 브랜드 컬러 중심 - 조정: 기능 - 제품 카테고리, 매장 찾기, 프로모션 배너 추가 - 비용: 제품 쇼케이스 모듈 설정과 이미지 자산 교체로 완료 ### 서비스 업종 - 유지: 전체 구조, 컴포넌트, API 패턴 - 조정: 비주얼 - 신뢰감 있는 스타일, 차분한 색상 - 조정: 기능 - 예약 시스템, 서비스 소개, 고객 후기 강화 - 비용: 예약 모듈 활성화와 콘텐츠 교체로 완료 ### Web3/블록체인 프로젝트 - 유지: 전체 구조, 컴포넌트, API 패턴 - 조정: 비주얼 - 다크 테마, 네온 액센트, 미래지향적 스타일 - 조정: 기능 - 토큰 정보, 로드맵, 커뮤니티 링크, 지갑 연동 추가 - 비용: 테마 설정과 커스텀 섹션 추가로 완료 --- ## 8. 엔지니어링 표준 및 모범 사례 **디렉토리 규칙** - 프론트엔드와 백엔드를 최상위에서 분리 - 공통 타입과 유틸리티는 `shared`에 배치 - 각 프로젝트는 `projects/[company-name]`에 격리 **네이밍 규칙** - 컴포넌트: PascalCase (예: `HeaderNav`, `ProductCard`) - 함수/변수: camelCase (예: `getConfig`, `isActive`) - API 엔드포인트: kebab-case (예: `/api/v1/site-config`) - 설정 키: snake_case (예: `brand_primary_color`) **스타일 관리 규칙** - CSS Modules 또는 Tailwind CSS를 사용하여 컴포넌트 스타일 격리 - 전역 스타일은 테마 변수로만 관리 - 색상, 폰트, 간격은 토큰으로 정의 **API 규칙** - 모든 API는 `/api/v1/` 접두어 사용 - 응답 형식 통일: `{ success, data, error }` - 에러 코드는 HTTP 상태 코드 + 앱 코드 조합 **설정 관리 규칙** - 설정 파일은 `config/` 디렉토리에 브랜드별로 분리 - 환경 변수는 `.env` 파일로 관리하고, `.env.example`을 제공 - 설정 변경은 반드시 버전 관리에 포함 **환경 변수 규칙** - `NODE_ENV`, `DATABASE_URL`, `API_BASE_URL` 등은 환경 변수로 관리 - 브랜드별 설정은 환경 변수가 아닌 설정 파일로 관리 **주석 및 문서화 규칙** - 모든 컴포넌트와 API는 JSDoc/TSDoc 형식으로 문서화 - `docs/` 디렉토리에 시스템 구조, 설정 방법, 확장 가이드를 유지 - 코드 변경 시 문서도 함께 업데이트 **프론트엔드-백엔드 협업 규칙** - API 계약은 `shared/types`에 정의하고 양쪽에서 import - API 변경 시 반드시 계약 문서를 먼저 업데이트 - 개발 환경에서는 목 서버를 사용하여 병렬 개발 가능 **유지보수 권장사항** - 모든 의존성은 버전을 고정하고 정기적으로 업데이트 - 테스트는 핵심 로직(설정 로딩, API 응답, 권한 검사)에 우선 작성 - CI/CD 파이프라인에서 빌드, 테스트, 배포를 자동화 --- ## 9. 권장 디렉토리 구조 ``` / ├── frontend/ │ ├── src/ │ │ ├── components/ # 재사용 컴포넌트 │ │ ├── pages/ # 페이지 컴포넌트 │ │ ├── hooks/ # 공통 훅 │ │ ├── styles/ # 테마, 글로벌 스타일 │ │ └── utils/ # 유틸리티 함수 │ ├── public/ │ │ └── assets/ # 이미지, 폰트 │ └── package.json │ ├── backend/ │ ├── src/ │ │ ├── api/ # API 라우터 │ │ ├── services/ # 비즈니스 로직 │ │ ├── models/ # 데이터 모델 │ │ ├── middlewares/ # 인증, 로깅 등 │ │ └── utils/ # 유틸리티 함수 │ ├── tests/ │ └── package.json │ ├── config/ │ ├── brands/ # 브랜드별 설정 파일 │ │ ├── tech-company.json │ │ ├── retail-company.json │ │ └── default.json │ └── features/ # 기능 모듈 설정 │ ├── assets/ │ ├── images/ # 공통 이미지 자산 │ ├── fonts/ # 공통 폰트 │ └── icons/ # 공통 아이콘 │ ├── shared/ │ ├── types/ # 공통 타입 정의 │ ├── utils/ # 공통 유틸리티 │ └── constants/ # 공통 상수 │ ├── docs/ │ ├── architecture.md # 시스템 구조 문서 │ ├── configuration.md # 설정 방법 문서 │ ├── extension-guide.md # 확장 가이드 │ └── api-contract.md # API 계약 문서 │ └── projects/ └── [company-name]/ # 프로젝트별 커스텀 코드 ``` 각 레이어의 책임: - `frontend/`: UI 렌더링, 사용자 인터랙션 - `backend/`: API 제공, 데이터 처리, 권한 관리 - `config/`: 브랜드 및 기능 설정 - `assets/`: 공통 리소스 관리 - `shared/`: 프론트엔드와 백엔드가 공유하는 타입과 유틸리티 - `docs/`: 시스템 문서화 - `projects/`: 프로젝트별 커스텀 코드 격리 --- ## 10. MVP 개발 우선순위 ### Phase 1: 최소 기능 골격 우선 개발 항목: - 기본 페이지 구조(홈, 소개, 제품/서비스, 문의) - 헤더/푸터/배너/폼 핵심 컴포넌트 - 브랜드 설정 로딩 메커니즘 - 기본 API(설정, 콘텐츠, 폼 제출) - 관리자 인증 및 기본 권한 이유: - 이 항목들이 없으면 시스템의 기본 구조가 성립하지 않음 - 이 단계에서 구조적 골격을 확정해야 이후 확장이 안정적 해결 문제: - "어떤 구조로 시작할 것인가"를 확정 - 브랜드 교체가 가능한 최소 수준의 설정 체계를 구축 템플릿 재사용 가치: - 이 골격만으로도 단순 기업 소개 사이트는 즉시 런칭 가능 - 이후 프로젝트에서 이 골격을 그대로 복제하여 사용 ### Phase 2: 경험 및 확장성 강화 우선 개발 항목: - 블로그, FAQ, 채용 페이지 모듈 - 다국어 지원 - SEO 최적화 - 반응형 디자인 완성 - 관리자 콘텐츠 편집 기능 이유: - 이 항목들은 대부분의 기업 사이트에서 요구되는 공통 기능 - Phase 1의 골격 위에 모듈을 추가하는 방식으로 구현 해결 문제: - "기능을 어떻게 추가할 것인가"를 확정 - 비개발자가 콘텐츠를 관리할 수 있는 체계를 구축 템플릿 재사용 가치: - 이 단계에서 대부분의 기업 사이트 요구사항을 충족 - 기능 모듈을 켜고 끄는 방식으로 프로젝트 범위를 조절 가능 ### Phase 3: 고급 기능 및 장기 진화 우선 개발 항목: - 서드파티 통합(CRM, 이메일 마케팅, 결제) - 고급 분석 및 모니터링 - A/B 테스트 기능 - 커스텀 페이지 빌더 - 다중 브랜드 동시 운영 이유: - 이 항목들은 특정 프로젝트에서만 필요한 고급 기능 - 시스템이 안정화된 후에 추가해도 기존 구조를 해치지 않음 해결 문제: - "시스템을 어떻게 장기적으로 발전시킬 것인가"를 확정 - 프로젝트별 특수 요구사항을 수용할 수 있는 확장 경로를 확보 템플릿 재사용 가치: - 이 단계에서 시스템은 단순 템플릿을 넘어 완전한 웹사이트 플랫폼으로 진화 - 다양한 산업의 요구사항을 수용할 수 있는 범용성을 확보 --- ## 11. 위험 및 경계 **과도한 일반화로 인한 브랜드 정체성 약화** - 위험: 모든 브랜드가 동일한 구조를 사용하면 차별성이 사라짐 - 통제: 브랜드별 비주얼 설정 범위를 넓히고, 커스텀 CSS 주입 지점을 제공 **과도한 설정 가능성으로 인한 시스템 복잡성 증가** - 위험: 설정 항목이 많아지면 시스템이 무거워지고 사용이 어려워짐 - 통제: 설정 항목을 필수/선택/고급으로 분류하고, 기본값을 명확히 제공 **과도한 백엔드 설계로 MVP 비용 증가** - 위험: 처음부터 모든 기능을 포함한 백엔드를 설계하면 개발 기간이 길어짐 - 통제: MVP는 최소한의 백엔드만 구현하고, 기능은 단계적으로 추가 **산업 간 차이가 커서 템플릿 적응 효율이 낮아지는 문제** - 위험: 산업별 요구사항이 너무 다르면 템플릿 재사용 이점이 줄어듦 - 통제: 산업별로 설정 템플릿을 제공하고, 커스텀 모듈은 `projects/`에 격리 --- ## 12. 최종 결론 **가장 권장하는 전체 접근 방식:** 설정 기반의 모듈형 템플릿 시스템. 고정된 구조적 골격 위에 브랜드 설정과 기능 모듈을 조합하는 방식으로, 각 프로젝트는 설정 파일과 콘텐츠 교체만으로 완성한다. **가장 권장하는 프론트엔드-백엔드 기술 스택:** - 프론트엔드: Next.js + TypeScript + Tailwind CSS - 백엔드: Node.js + Express + TypeScript - 데이터베이스: PostgreSQL - 배포: Docker + CI/CD 파이프라인 **가장 먼저 구축할 버전:** Phase 1의 최소 기능 골격. 기본 페이지 구조, 핵심 컴포넌트, 브랜드 설정 로딩, 기본 API, 관리자 인증만 포함한다. **향후 확장 경로:** Phase 1 골격을 기반으로 Phase 2에서 블로그, FAQ, 다국어, SEO를 추가하고, Phase 3에서 서드파티 통합과 커스텀 페이지 빌더를 도입한다. **가장 큰 장점:** 한 번 구축한 구조를 모든 프로젝트에 재사용하여 개발 시간을 60~70% 단축하고, 유지보수 인력이 시스템 구조를 한 번만 학습하면 모든 프로젝트를 관리할 수 있다. **가장 주의해야 할 문제:** 과도한 설정 가능성과 일반화로 인해 시스템이 비대해지고 복잡해지는 것. 설정 항목은 필수/선택/고급으로 분류하고, 기본값을 명확히 제공하여 복잡성을 통제해야 한다.