voidX AI는 AI 크롤러(GPT, Perplexity 등)가 신뢰할 수 있는 정보 소스로 인식하도록 설계된 GEO(Generative Engine Optimization) 최적화 리소스 시스템을 구축했습니다. 이 문서에서는 시스템의 설계 철학과 기술적 구현 방법을 상세히 설명합니다.
설계 철학#
"우리의 목표는 기계와 인간 모두가 쉽게 이해할 수 있는 콘텐츠를 만드는 것입니다. 구조화된 데이터와 시맨틱 HTML을 통해 AI 크롤러가 정보를 정확하게 파악하고, 동시에 사용자에게는 뛰어난 읽기 경험을 제공합니다." — voidX Engineering Team
핵심 원칙#
- 기계 친화적 구조: Schema.org JSON-LD를 통한 구조화된 데이터 제공
- 다국어 확장성: Locale suffix 방식의 유연한 번역 관리
- 백엔드 독립성: Repository Pattern을 통한 데이터 소스 추상화
- 개발자 경험: Git 기반 콘텐츠 관리로 빠른 반복 개발
아키텍처 개요#
시스템은 크게 세 개의 레이어로 구성됩니다:
Presentation Layer#
사용자에게 보여지는 UI 컴포넌트들입니다:
- ResourceListPage: 카테고리 필터와 그리드 레이아웃을 제공하는 목록 페이지
- ResourceDetailPage: OpenAI 스타일의 모노톤 디자인을 적용한 상세 페이지
- AdminEditPage: 마크다운 에디터를 통한 콘텐츠 관리 인터페이스
Data Access Layer#
데이터 소스에 대한 추상화 레이어입니다:
- IResourceRepository: 조회/생성/수정/삭제를 위한 인터페이스 정의
- GitResourceRepository: 파일 시스템 기반 구현 (Phase 1)
- ApiResourceRepository: 백엔드 API 연동 구현 (Phase 2)
Content Layer#
실제 콘텐츠가 저장되는 영역입니다:
- Markdown Files: gray-matter를 통한 frontmatter 파싱
- Asset Storage: cdn.voidx.ai를 통한 이미지 최적화
기술 스택#
| 카테고리 | 기술 | 버전 |
|---|---|---|
| Framework | Next.js | 16.1 |
| Runtime | React | 19.2 |
| Markdown | react-markdown + remark-gfm | 10.x |
| Frontmatter | gray-matter | 4.0 |
| Editor | @uiw/react-md-editor | 4.0 |
| Styling | Tailwind CSS | 4.1 |
| i18n | next-intl | 4.7 |
다국어 콘텐츠 전략#
voidX는 Locale Suffix 방식의 다국어 관리를 채택했습니다:
content/resources/
└── voidx-resource-architecture/
├── index.md # 기본(ko) - 필수
└── index.en.md # 영문 - 선택
폴백 전략#
- 요청 locale의 파일이 존재하면 해당 파일 반환
- 파일이 없으면 기본(ko) 파일 반환 +
isTranslated: false플래그 설정 - UI에서 "이 콘텐츠는 아직 번역되지 않았습니다" 안내 표시
이 방식의 장점:
- 기존 i18n 폴더 구조와 일관성 유지
- 번역 진행 상황을 파일 존재 여부로 쉽게 파악
- 백엔드 전환 시 locale 필드로 자연스럽게 매핑
GEO 최적화 전략#
JSON-LD 구조화 데이터#
모든 리소스 페이지에는 세 가지 Schema.org 스키마가 포함됩니다:
- Article: 제목, 발행일, 수정일, 저자, 이미지 등 기사 메타데이터
- Organization: voidX AI 회사 정보 및 소셜 링크
- BreadcrumbList: 홈 → Resources → 카테고리 → 글 경로
시맨틱 HTML 구조#
마크다운 렌더러는 의미론적으로 올바른 HTML 태그를 출력합니다:
<article>: 전체 콘텐츠 래퍼<section>: 각 H2 섹션<figure>/<figcaption>: 이미지와 캡션<blockquote>: 인용문
RSS 피드#
/resources/rss.xml 엔드포인트를 통해 RSS 2.0 피드를 제공합니다. AI 크롤러들이 새 콘텐츠를 빠르게 발견할 수 있도록 합니다.
백엔드 연동 가이드#
Phase 2에서 백엔드 API로 전환할 때 필요한 엔드포인트 명세입니다:
| Method | Endpoint | 설명 |
|---|---|---|
| GET | /resource?locale={locale} | 목록 조회 |
| GET | /resource/{slug}?locale={locale} | 상세 조회 |
| GET | /resource/slugs | 전체 slug 목록 |
| POST | /resource | 생성 (Admin) |
| PUT | /resource/{slug} | 수정 (Admin) |
| DELETE | /resource/{slug} | 삭제 (Admin) |
전환 방법:
lib/resources/apiRepository.ts구현 완료- 환경변수
RESOURCE_PROVIDER=api설정 - 코드 변경 없이 즉시 전환 완료
결론#
voidX 리소스 시스템은 다음과 같은 가치를 제공합니다:
- 즉시 사용 가능: Git 기반으로 마크다운 파일만 추가하면 바로 배포
- 확장 준비 완료: Repository Pattern으로 백엔드 연동 시 무중단 전환
- GEO 최적화: 구조화된 데이터로 AI 크롤러 신뢰도 확보
- 개발자 친화적: 익숙한 마크다운 작성 환경과 Admin UI 제공
이 아키텍처를 기반으로 voidX AI는 기업 정보, 제품 문서, 사용 사례 등 다양한 콘텐츠를 효과적으로 관리하고 배포할 수 있습니다.