Next.js 15 (App Router)  ←→  FastAPI (Python)  ←→  PostgreSQL (Neon)
                                     ↓
                             Anthropic Claude API
...

interface BusinessBrief {
  businessName: string;
  businessType: string;       // "Restaurant", "Law firm", "Tech startup" 등
...

@router.post("/onboarding")
async def complete_onboarding(
    body: OnboardingRequest,
...

async def generate_home_page(brief: BusinessBrief) -> dict:
    system = """
You are a professional web designer generating page content for Nigerian businesses.
...
"""

async def critic_review(brief: BusinessBrief, draft: dict) -> dict:
    critique_prompt = f"""
Review this website draft for {brief.business_name} ({brief.business_type}).
...
"""

async def generate_subpages(site_id: int, brief: BusinessBrief):
    pages_to_generate = ["about", "services", "contact"]
    tasks = [generate_page(brief, page) for page in pages_to_generate]
...

{
  "root": { "props": {} },
  "content": [
...

블록 스키마 (엄격함 — 오직 이 키들만 사용):

HeroSection:
...

async def generate_with_retry(brief, page_type, max_attempts=3):
    for attempt in range(max_attempts):
        try:
...
```

```$', '', raw.strip(), flags=re.MULTILINE)
            return json.loads(cleaned)
        except json.JSONDecodeError:
            if attempt == max_attempts - 1:
...
```

마크다운 펜스(markdown fence) 제거는 가장 흔한 실패 모드를 처리합니다. Claude는 JSON을 사용하지 말라고 지시받았음에도 불구하고 가끔 `json` 코드 블록으로 감싸는 경우가 있기 때문입니다.

## 이미지 소싱 (Image Sourcing)

생성된 페이지는 URL이 아닌 의미론적 쿼리(semantic query)를 통해 이미지를 참조합니다. 콘텐츠 생성 후, 두 번째 비동기(async) 단계에서 자동으로 도출된 검색어를 사용하여 Stock Photos API에 쿼리를 보냅니다:

```
async def hydrate_images(site: Site, page_content: dict) -> dict:
    """의미론적 이미지 플레이스홀더(placeholder)를 실제 Stock Photo API의 URL로 교체합니다."""
    for block in page_content.get("content", []):
...
```

LLM은 URL 대신 `backgroundImageQuery: "nigerian bakery fresh bread"`를 출력합니다. 하이드레이션(hydration) 단계는 검증(validation) 후에 실행되므로, 이미지 가져오기에 실패하더라도 페이지 저장 과정이 중단되지 않습니다.

## 나이지리아 특화 디자인 결정 사항

### 결제: Stripe가 아닌 Paystack

Paystack은 나이지리아 카드 결제의 사실상 표준(de facto standard)입니다. 통합 범위는 다음과 같습니다:

- Paystack 대시보드에서 관리되는 플랜 코드가 포함된 월간 및 연간 결제 플랜
- 웹훅(Webhook) 기반의 구독 상태 머신 (charge.success → 활성화, subscription.not_renew → 비활성화)
- 전 과정에 걸친 나이라(Naira) 금액 사용 — 통화 변환의 복잡성 없음

연간 결제를 구현하려면 마케팅 가격 페이지의 `interval` 선택 사항을 가입 → 온보딩(onboarding) → 백엔드(backend) → Paystack 플랜 코드 선택까지 모두 전달해야 했습니다. 핵심적인 아키텍처 포인트는 `interval`을 Paystack 웹훅 메타데이터에 저장하는 것입니다. 이를 통해 사용자가 결제를 시작한 시점과 완료한 시점 사이에 브라우저가 충돌하더라도 올바른 플랜이 활성화될 수 있습니다.

### 커스텀 도메인: Cloudflare for SaaS

모든 사이트는 무료 서브도메인(`yourstore.webdigitize.com`)을 할당받습니다. 유료 플랜 사용자는 커스텀 도메인(Custom Domain)을 연결할 수 있습니다. 이는 Cloudflare for SaaS를 통해 작동합니다. 각 커스텀 도메인은 Cloudflare Custom Hostname으로 등록되며, 이를 통해 당사 측에서 사이트별로 별도의 DNS 설정을 할 필요 없이 SSL 프로비저닝(Provisioning)과 CNAME 라우팅(Routing)을 처리합니다.

Next.js 미들웨어(Middleware)는 들어오는 호스트네임(Hostname)을 읽어 올바른 사이트로 라우팅하고, 해당 사이트의 테마 토큰(Theme tokens)과 콘텐츠를 주입합니다. 단 한 번의 배포로 수천 개의 상점을 서비스할 수 있습니다.

### 기본 CTA로서의 WhatsApp

대부분의 나이지리아 중소기업(SMBs)에게 WhatsApp은 이메일이나 문의 양식이 아닌, 주요 비즈니스 커뮤니케이션 채널입니다. AI 생성 파이프라인(Pipeline)은 전화번호가 사용 가능한 경우, 기본 CTA(Call to Action)를 WhatsApp 딥링크(`https://wa.me/{phone}`)로 설정하도록 지시받습니다. 이것만으로도 고객을 위해 생성된 사이트의 전환율(Conversion rate)을 유의미하게 높일 수 있습니다.

## 내가 실수했던 점 (그리고 해결한 점)

**1. AI로 쇼핑 페이지를 생성하려고 시도한 것**

첫 번째 반복(Iteration)에서는 Claude에게 쇼핑 페이지 레이아웃을 생성하도록 요청했습니다. 결과물은 정적으로는 괜찮아 보였지만, 제품 데이터, 장바구니 통합, 실시간 재고가 없는 '죽은' 페이지였습니다. 일부 페이지는 콘텐츠가 아닌 코드가 필요하다는 사실을 받아들이기 전까지 일주일이라는 시간을 허비했습니다.

**2. 단일 프롬프트에 너무 많은 내용을 담은 것**

첫 세대의 홈 페이지 프롬프트는 2,000토큰(Token) 분량의 지시 블록을 사용하여 한 번에 6개 섹션을 모두 생성하려고 시도했습니다. 출력 품질은 일관되지 않았습니다. 이를 '생성 패스(Generation pass)'와 짧은 프롬프트를 사용한 '집중 비평 패스(Focused critic pass)'로 나누자, 프롬프트 엔지니어링(Prompt engineering) 노력을 덜 들이고도 훨씬 더 나은 결과를 얻을 수 있었습니다.

**3. 스키마 계층에서 `props`를 고정하지 않은 것**

초기 컴포넌트들은 유연한 `props`를 가졌습니다. 즉, 어떤 키(key)든 허용되었고, 누락된 키는 기본값(defaults)으로 대체되었습니다. 이는 LLM의 작업을 더 쉽게 만드는 것처럼 느껴졌지만, 검증 오류(validation errors)를 렌더링 시점(render time)으로 미루게 만들었고, 그곳에서 오류는 소리 없이 지나갔습니다. 스키마 경계(schema boundary)에서 런타임 검증(runtime validation)을 포함한 엄격한 TypeScript 프롭 타입(prop types)으로 전환함으로써, 환각(hallucinated)된 키를 즉시 잡아낼 수 있었고 개발 과정에서 더 깔끔한 에러 메시지를 얻을 수 있었습니다.

**4. HTTP 응답을 차단하는 동기식 생성 (Synchronous generation)**

첫 번째 버전은 요청 핸들러(request handler) 내부에서 생성 과정을 `await` 했습니다. 4페이지 분량의 사이트의 경우, 이는 15~25초의 HTTP 응답 시간을 의미했습니다. FastAPI의 `BackgroundTasks`가 이 문제를 해결했습니다. 응답은 작업 ID(job ID)와 함께 즉시 반환되고, 클라이언트는 `/status` 엔드포인트를 폴링(poll)하며, Server-Sent Event(SSE)가 "준비 완료" 신호를 푸시합니다. 사용자는 빈 스피너 대신 진행 애니메이션을 보게 됩니다.

## 성능 및 비용

- 평균 홈 페이지 생성 시간: **8~12초** (두 번의 Claude API 호출)
- 평균 전체 사이트 (4페이지): **20~35초** (하위 페이지 병렬 생성)
- 생성된 사이트당 Claude API 비용: 대규모 운영 시 **우리의 마진(margin) 범위 내에 충분히 들어옵니다.**
- 스톡 사진(Stock Photos) API: 무료 티어는 시간당 200개의 요청을 지원하며, 현재 물량에는 충분하고도 남습니다.

생성당 비용은 월간 구독 수익에 비해 무시할 수 있는 수준입니다.

## 에디터: Puck

사이트가 생성되면, 사용자는 대시보드에 내장된 Puck 드래그 앤 드롭(drag-and-drop) 에디터를 통해 직접 편집할 수 있습니다. AI가 생성하는 것과 동일한 JSON 스키마를 에디터가 사용하므로, 사람이 수정한 내용과 AI가 재생성한 결과물은 동일한 형식으로 생성되어 동일한 데이터베이스 컬럼에 저장됩니다.

이것이 핵심적인 아키텍처 측면의 승리입니다: **AI는 에디터로 결과물을 넘겨주는 별개의 시스템이 아닙니다.** AI는 사람이 계속해서 편집할 수 있는 데이터 구조를 위한 초기화 도구(initialiser)입니다. 생성 후 아무런 관여를 원하지 않는 사용자는 즉시 라이브 웹사이트를 갖게 됩니다. 커스터마이징을 원하는 사용자는 완전한 시각적 에디터를 사용할 수 있습니다.

## 미결 과제 및 향후 작업

- **점진적 재생성 (Incremental regeneration)**: 페이지의 나머지 부분은 건드리지 않고 "서비스 섹션만 다시 생성해줘"라고 사용자가 요청할 수 있도록 합니다.
- **음성 기반 브리프 (Voice-driven brief)**: 60초 분량의 오디오 설명을 녹음하고, 이를 Whisper로 전사(transcribe)하여 생성 브리프(generation brief)로 사용합니다. 이는 기술에 익숙하지 않은 사용자들에게 타이핑이라는 장벽마저 제거해 줍니다.
- **수락/거부된 출력물에 대한 미세 조정 (Fine-tuning on accepted/rejected outputs)**: 사용자가 생성된 사이트 중 어느 부분을 집중적으로 수정하는지(초기 품질이 낮다는 신호) 추적하고, 이를 학습 신호로 사용합니다.
- **다국어 생성 (Multilingual generation)**: 영어가 주 언어가 아닌 사용자를 위해 요루바어(Yoruba), 하우사어(Hausa), 이보어(Igbo) UI 및 콘텐츠 생성을 지원합니다.

## 결론 (Conclusion)

이 프로젝트를 구축하며 배운 점은, AI 제품 개발에서 어려운 부분은 모델 자체가 아닌 경우가 많다는 것입니다. 진짜 어려운 것은 모델의 출력물과 나머지 시스템 사이의 인터페이스, 즉 스키마 설계 (schema design), 검증 (validation), 우아한 성능 저하 (graceful degradation), 그리고 피할 수 없는 지연 시간 (latency) 주변의 사용자 경험 (user experience)입니다.

이중 패스 생성 (dual-pass generation) + 비평가 (critic) 아키텍처는 출력 품질을 개선하기 위해 제가 수행한 가장 영향력 있는 작업이었습니다. 시스템 프롬프트 내 스키마 삽입 (schema-in-system-prompt) 트릭이 그 뒤를 바짝 쫓고 있습니다.

만약 여러분이 이와 유사한 것을 구축하고 있다면, 저의 권장 사항은 다음과 같습니다: