[DOCS] BrandKit 공개 저장소 신뢰성 보강

README.md

@@ -1,119 +1,100 @@
-# BrandKit (Charlotte)
+# BrandKit
 
-AI 기반 브랜드 에셋 자동 생성 SaaS 플랫폼
+[![CI](https://github.com/jadru/brand-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/jadru/brand-kit/actions/workflows/ci.yml)
+[![Next.js 16](https://img.shields.io/badge/Next.js-16-000000?logo=nextdotjs)](https://nextjs.org/)
+[![TypeScript strict](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)](./tsconfig.json)
 
-## 주요 기능
+브랜드 정보를 한 번 입력하면 웹·모바일용 아이콘, favicon, OG image, PWA manifest와 적용 코드를 생성해 ZIP으로 전달하는 SaaS 제품입니다.
 
-- **브랜드 프로필 관리**: 스타일, 색상, 아이콘 스타일 저장
-- **AI 헤드라인 생성**: Claude AI를 활용한 브랜드 카피 생성
-- **AI 아이콘 생성**: FAL.ai를 활용한 커스텀 아이콘 생성 (Pro)
-- **멀티플랫폼 에셋**: 웹 (Favicon, OG Image, PWA) 및 모바일 (App Icon, Splash) 지원
-- **원클릭 다운로드**: 모든 에셋을 ZIP 파일로 제공
+[Live product](https://brand-kit.jadru.com/ko) · [Try the public demo](https://brand-kit.jadru.com/ko/demo) · [Architecture](./docs/architecture/overview.md)
+
+## 제품 흐름
+
+1. 브랜드 이름, 설명과 스타일을 정의합니다.
+2. Web, Mobile 또는 전체 플랫폼을 선택합니다.
+3. AI copy·icon과 파생 asset을 생성합니다.
+4. 미리보기로 결과를 확인하고 적용 코드가 포함된 ZIP을 받습니다.
+
+<table>
+  <tr>
+    <td width="50%"><img src="./docs/assets/brandkit-wizard.png" alt="BrandKit platform selection step" /></td>
+    <td width="50%"><img src="./docs/assets/brandkit-asset-preview.png" alt="BrandKit generated asset preview" /></td>
+  </tr>
+  <tr>
+    <td align="center">플랫폼별 asset wizard</td>
+    <td align="center">생성 결과 preview와 ZIP download</td>
+  </tr>
+</table>
+
+## Engineering highlights
+
+- **명시적인 경계:** TypeScript `strict` mode를 사용하고 form 입력은 Zod schema로 검증합니다.
+- **분리된 asset pipeline:** favicon, OG image, PWA, app icon, splash와 code snippet 생성을 독립 모듈로 나누고 마지막 단계에서 ZIP으로 조합합니다.
+- **안전한 delivery:** GitHub Actions가 lint, type check, Vitest와 production build를 모두 통과해야 완료됩니다.
+- **배포 후 검증:** production QA script가 public route, locale redirect, SEO endpoint, image response와 ZIP 내부 파일 계약을 실제 배포 URL에서 확인합니다.
+- **보안 경계:** Supabase Auth·RLS로 사용자 데이터를 격리하고, 결제 webhook은 HMAC signature를 constant-time으로 검증합니다.
 
 ## 기술 스택
 
-| 카테고리 | 기술 |
-|---------|------|
-| Framework | Next.js 15 (App Router, Turbopack) |
-| UI | React 19, Tailwind CSS v4, CVA |
-| State | Zustand |
-| Database | Supabase (PostgreSQL + Auth + Storage) |
-| AI | Claude (Anthropic), FAL.ai |
-| Payment | LemonSqueezy |
-| Testing | Vitest |
-| Deployment | Vercel |
+| 영역 | 기술 |
+|---|---|
+| Web | Next.js 16, React 19, TypeScript, Tailwind CSS v4 |
+| State & Form | Zustand, React Hook Form, Zod |
+| Data | Supabase PostgreSQL, Auth, Storage |
+| AI & Payment | Anthropic, FAL.ai, LemonSqueezy |
+| Quality | Vitest, Testing Library, ESLint, GitHub Actions |
+| Delivery | Vercel, production QA script |
 
-## 시작하기
+## 로컬 실행
 
-### 필수 조건
+### 요구사항
 
-- Node.js 22+
+- Node.js 22.12+
 - Yarn 4+
-- Supabase 프로젝트
-
-### 설치
+- Supabase project
 
 ```bash
-# 의존성 설치
 yarn install
-
-# 환경변수 설정
 cp .env.example .env.local
-# .env.local 파일을 편집하여 필요한 값 입력
-
-# 개발 서버 실행
 yarn dev
 ```
 
-### 환경변수
+필요한 환경변수와 server/client 노출 경계는 [`.env.example`](./.env.example)에 정리되어 있습니다.
 
-```env
-# Supabase
-NEXT_PUBLIC_SUPABASE_URL=https://[project-id].supabase.co
-NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=eyJ...
-SUPABASE_SERVICE_ROLE_KEY=eyJ...
-
-# AI Services
-ANTHROPIC_API_KEY=sk-ant-...
-FAL_KEY=...
-
-# LemonSqueezy
-LEMONSQUEEZY_API_KEY=...
-LEMONSQUEEZY_STORE_ID=...
-LEMONSQUEEZY_WEBHOOK_SECRET=...
-LEMONSQUEEZY_PRO_VARIANT_ID=...
-
-# App
-NEXT_PUBLIC_APP_URL=http://localhost:3000
-```
-
-## 스크립트
+## 검증
 
 ```bash
-yarn dev          # 개발 서버 (Turbopack)
-yarn build        # 프로덕션 빌드
-yarn start        # 프로덕션 서버
-yarn lint         # ESLint 실행
-yarn test         # 테스트 실행
-yarn test:watch   # 테스트 워치 모드
-yarn test:coverage # 커버리지 포함 테스트
+yarn lint
+yarn tsc --noEmit
+yarn test
+yarn build
+
+# 배포된 제품의 route·binary contract 확인
+yarn qa:preview https://brand-kit.jadru.com
 ```
 
 ## 프로젝트 구조
 
-```
-├── app/                    # Next.js App Router
-│   ├── (auth)/            # 인증 페이지
-│   ├── (dashboard)/       # 대시보드 페이지
-│   └── api/               # API 라우트
-├── components/            # React 컴포넌트
-│   ├── ui/               # 기본 UI 컴포넌트
-│   ├── landing/          # 랜딩페이지 섹션
-│   └── wizard/           # 프로젝트 생성 위저드
-├── lib/                   # 유틸리티 및 서비스
-│   ├── ai/               # AI 서비스 (Claude, FAL)
-│   ├── assets/           # 에셋 생성 파이프라인
-│   ├── supabase/         # Supabase 클라이언트
-│   └── utils/            # 유틸리티 함수
-├── store/                 # Zustand 상태 관리
-├── types/                 # TypeScript 타입 정의
-├── tests/                 # 테스트 파일
-└── docs/                  # 문서
-    ├── architecture/     # 아키텍처 문서
-    ├── guides/           # 개발 가이드
-    ├── maintenance/      # 유지보수 가이드
-    └── decisions/        # ADR (Architecture Decision Records)
+```text
+app/                    Next.js pages, server actions, API routes
+components/             Product UI and reusable primitives
+lib/
+  ai/                   AI provider boundaries and prompt configuration
+  assets/               Asset generation and ZIP packaging pipeline
+  security/             Rate limiting and security helpers
+  supabase/             Server/client data access
+store/                  Wizard client state
+tests/                  API, component, configuration and asset tests
+docs/                   Architecture decisions, guides and QA reports
 ```
 
-## 문서
+## 주요 문서
 
-- [아키텍처 개요](./docs/architecture/overview.md)
-- [에러 처리 가이드](./docs/guides/error-handling.md)
-- [테스트 전략](./docs/guides/testing-strategy.md)
-- [타입 안전성 가이드](./docs/guides/type-safety.md)
-- [배포 가이드](./docs/maintenance/deployment-guide.md)
-- [코드 리뷰 가이드](./docs/maintenance/code-review-guide.md)
+- [Architecture overview](./docs/architecture/overview.md)
+- [Error handling guide](./docs/guides/error-handling.md)
+- [Preview QA report](./docs/reports/2026-05-07-brandkit-preview-qa.md)
+- [Deployment guide](./docs/maintenance/deployment-guide.md)
 
-## 라이선스
+## License
 
-Private
+소스 코드는 공개되어 있지만 별도의 오픈소스 라이선스는 부여하지 않았습니다.

docs/architecture/overview.md

@@ -4,7 +4,7 @@
 
 ```
 BrandKit (Charlotte)
-├── Frontend (Next.js 15 App Router)
+├── Frontend (Next.js 16 App Router)
 │   ├── 랜딩페이지 (/)
 │   ├── 인증 (/login, /signup)
 │   └── 대시보드 (/dashboard, /projects, /brand-profiles, /settings)
@@ -29,7 +29,7 @@ BrandKit (Charlotte)
 
 | 레이어 | 기술 |
 |--------|------|
-| Framework | Next.js 15 (App Router, Turbopack) |
+| Framework | Next.js 16 (App Router, Turbopack) |
 | UI | React 19, Tailwind CSS v4, CVA |
 | State | Zustand |
 | Database | Supabase (PostgreSQL + Auth + Storage) |
@@ -94,5 +94,8 @@ ZIP 패키징 → Supabase Storage 업로드
 - 정적 에셋: Vercel Edge Cache
 
 ## 관련 문서
-- [데이터 흐름](./data-flow.md)
-- [컴포넌트 구조](./component-structure.md)
+
+- [에러 처리 가이드](../guides/error-handling.md)
+- [타입 안전성 가이드](../guides/type-safety.md)
+- [테스트 전략](../guides/testing-strategy.md)
+- [배포 가이드](../maintenance/deployment-guide.md)