Skip to main content

🚀 Quick Start Guide - 5分でNekomataを理解

🎯 目標: 5分でシステム全体を理解し、即座に開発・運用作業に取りかかれる

📋 システム概要 (60秒)​

📸 What: 高品質89mm正方形写真プリントサービス
🏢 Who: マルチブランド対応 (Nekomata, TOKINOE, Dog)  
🛠️ How: Cloudflare + Shopify + Firebase のサーバーレス構成
🎯 Why: ユーザー体験重視 + 開発効率最大化 + コスト最適化

⚡ 核心アーキテクチャ​

📱 Apps (iOS/Android/Web) 
    ↓ Firebase Auth
🔗 BFF (Cloudflare Workers)
    ↓ Queue System  
🛒 Shopify (注文・決済・個人情報)
📊 D1 Database (非PII・設定・ログ)

🎯 役割別スタートポイント (60秒)​

👨‍💼 Product Manager → ビジネス理解​

  1. 要件定義 ← ビジネス要件全体
  2. ブランド管理 ← 各ブランド詳細
  3. Phase実装 ← 開発スケジュール

👨‍💻 Developer → 技術実装​

  1. 開発環境構築 ← 即座に開始
  2. BFF概要 ← システム中核理解
  3. API設計 ← 実装仕様詳細

🔧 DevOps/SRE → インフラ運用​

  1. システム設計 ← 全体構成
  2. 技術制約 ← 制限事項・考慮点
  3. セキュリティ ← 保護メカニズム

🔄 重要コンセプト理解 (90秒)​

🎨 Multi-Brand Architecture​

// 1つのシステムで3ブランド同時運用
const brands = {
  neko: { domain: 'neko.contents-print.jp', shopify: 'neko-store' },
  tokinoe: { domain: 'tokinoe.contents-print.jp', shopify: 'tokinoe-store' },  
  dog: { domain: 'tbd', shopify: 'tbd' }
}

🛡️ Privacy by Design​

PII_RULE: "個人情報は100%Shopifyに集約、D1には一切保存しない"
  D1_STORES: "Firebase UID, 設定, 非識別情報のみ"  
  SHOPIFY_STORES: "名前, 住所, メール, 注文履歴"
  BFF_RULE: "中継のみ、保存禁止"

⚡ Queue-First Architecture​

// Shopify API制限(40req/min)完全回避
async function createOrder(data) {
  // ❌ 直接API呼び出し → 制限リスク
  // return await shopify.orders.create(data) 
  
  // ✅ Queue経由 → 制限安全
  await QUEUE.send('ORDER_CONFIRMED', { order_id, brand })
  return { status: 'processing', order_id } // 即座レスポンス
}

🚀 即座開始アクション (60秒)​

🛠️ 開発者 - 3ステップセットアップ​

# Step 1: 環境構築 (詳細は development/setup)
git clone <repo> && cd nekomata
npm install

# Step 2: ローカル開発サーバー起動  
npm run dev

# Step 3: API動作確認
curl localhost:3000/api/health
# → {"status": "ok", "version": "v1.0.0-beta"}

📊 運用者 - 監視ポイント​

重要メトリクス:
  API応答: P95 < 200ms
  Queue遅延: P95 < 2秒  
  Shopify制限: 使用率 < 87% (35/40req)
  エラー率: < 0.1%

アラート設定:
  🚨 Critical: Shopify 429エラー > 5件/分
  ⚠️ Warning: Queue DLQ > 10件/時間

🎯 次のステップ選択​

やりたいこと次に読む文書所要時間
🔨 機能実装API設計15分
🗄️ DB設計理解D1設計10分
🔄 Queue実装Queue設計20分
🛡️ セキュリティセキュリティ実装15分
📱 アプリ連携Shopify統合12分
🔧 運用設定管理画面8分
❓ 困った時Developer Cheat Sheet2分

💡 Pro Tips​

🔍 効率的な文書ナビゲーション​

  • Ctrl+F: 文書内検索で即座に目的情報へ
  • サイドバー: 役割別カテゴリで迷わない
  • 関連リンク: 各文書末尾の「次のドキュメント」を活用

⚡ 開発スピードアップ​

  • Cheat Sheet: よく使うコード・コマンド集
  • AIメタデータ: Claude等AIとの協業時に活用
  • Implementation Status: 実装済み機能の確認に活用

🎊 完了! これでNekomataシステムの全体像と開発・運用への入り口が理解できました。
次のアクション: 上記「次のステップ選択」から、あなたの役割に応じた詳細文書へ進んでください。