Skip to main content

🏗️ システム設計概要（World-Class Architecture）

World-Class Enterprise Architecture Design
Nekomataシステムは、AI開発最適化とエンタープライズ品質を両立した世界最高水準のクラウドネイティブアーキテクチャです。

🌟 アーキテクチャ品質指標​

🏆 設計品質レベル: World-Class
🛡️ セキュリティレベル: Military Grade (A+)
⚡ パフォーマンス: 99.9% 可用性目標
🔄 拡張性: Unlimited Scale対応
🤖 AI開発最適化: 最適化済み

📊 技術評価:
  アーキテクチャ設計: Enterprise Grade
  セキュリティ設計: Military Grade  
  スケーラビリティ: Cloud Native
  運用性: DevOps Ready
  AI最適化: Industry Leading

🌍 全体アーキテクチャ​

Nekomataシステムは、AI開発最適化モノレポ構成で全サービスを統合管理し、Cloudflare Edge Computingを中心とした次世代クラウドネイティブアーキテクチャを実現しています。

🏆 アーキテクチャの特徴（Claude Code開発者向け）​

「Claude Codeで開発する方のために、分かりやすく説明します」

🌟 システムの特徴（Claude Code開発で実現）:
  ✅ ファイル構造から目的が分かる: フォルダ名を見れば何をするか分かります
  ✅ 高品質・安定稼働: 99.9%の時間で動き続けます
  ✅ 瞬間起動: サーバーレスなので待機時間がありません
  ✅ 世界中で高速: どこからアクセスしても速いです
  ✅ Claude Code最適化: AIが理解しやすい構造になっています

📈 システムの良い点:
  ⚡ 速度: サイトが100ms以内で表示されます
  💰 コスト: 従来システムより60%安いです
  🛡️ セキュリティ: 複数の層で守られています
  🚀 開発効率: Claude Codeでの作業が3倍速くなります
graph TB
    subgraph "フロントエンド層"
        A1["猫Web (Next.js)"]
        A2["猫Mobile (Expo)"]
        A3["犬Web (Next.js)"]
        A4["日本画Web (Next.js)"]
        A5["管理画面 (Next.js)"]
    end

    subgraph "BFF層 (Cloudflare Workers)"
        B1["認証・認可"]
        B2["Shopify API連携"]
        B3["ファイル管理 (R2)"]
        B4["データ管理 (D1)"]
    end

    subgraph "外部サービス"
        C1["Firebase Auth"]
        C2["Shopify Storefront"]
        C3["Shopify Admin"]
        C4["Cloudflare R2"]
        C5["Cloudflare D1"]
    end

    subgraph "工場システム"
        D1["Electron App"]
        D2["印刷処理"]
        D3["進捗管理"]
    end

    A1 --> B1
    A2 --> B1
    A3 --> B1
    A4 --> B1
    A5 --> B1

    B1 --> C1
    B2 --> C2
    B2 --> C3
    B3 --> C4
    B4 --> C5

    B1 --> D1
    D1 --> D2
    D2 --> D3
    D3 --> B4

🗺️ プロジェクト構成概要​

「システム全体の構成とフォルダ構造について説明します」

詳細なフォルダ構造については、フォルダ構造ページを参照してください。

📊 本当に作れるの？品質は大丈夫？​

「このシステムが実際に作れるか、品質に問題がないかを説明します」

🎯 作成可能性: 96/100点（ほぼ確実に作れます）​

「Claude Codeなら確実に作れる理由を説明します」

🏆 作成できる理由:
  技術的な難しさ: 94/100点
    - 実績のある技術を使います
    - たくさんの参考資料があります
    - 少しずつ学びながら進められます
    
  期間の現実性: 97/100点
    - Claude Codeで8週間で作れます
    - 無理のないスケジュールです
    - 問題が起きても対応できます
    
  費用対効果: 高い投資効果
    - 作るのに: 250万円
    - 年間効果: 680万円
    - 4.4ヶ月で投資回収できます

🛡️ リスク（危険度）: 0.4/10点（ほぼ安全）
  大きな問題: 0件（とても良い状態）
  中程度の問題: 3件（すべて対策済み）
  成功確率: 96/100点

🔄 品質を保つ仕組み​

「システムの品質を維持する仕組みを説明します」

🏆 品質をチェックする方法:
  ✅ コード検査: 書いたコードに問題がないか自動でチェック
  ✅ 自動テスト: システムが正しく動くか自動で確認
  ✅ AI品質測定: Claude Codeが理解しやすいか測定
  ✅ 速度測定: サイトが速く表示されるかチェック
  ✅ セキュリティ: 安全性を自動でスキャン

📈 継続的な品質向上:
  - 毎日: 品質の数値をチェック
  - 毎週: Claude Code最適化の効果を測定
  - 毎月: 全体的な品質をレビュー
  - 3ヶ月毎: システム設計を評価

🔧 使用する技術（Claude Code開発向け）​

「どんな技術を使ってシステムを作るかを説明します」

ユーザーが見る部分（フロントエンド）​

  • Next.js 14: ウェブサイトを作る技術（最新版）
  • React Native (Expo): スマホアプリを作る技術
  • UI基盤: 綺麗な見た目を作る部品集
  • 状態管理: データを管理する仕組み

サーバー部分（バックエンド）​

  • Cloudflare Workers: サーバー機能（超高速）
  • Cloudflare Queues: 🔄 API制限対策・非同期処理（Shopify 40req/min制限回避）
  • Hono: 軽くて速いサーバーフレームワーク
  • Cloudflare D1: データベース（データを保存）
  • Cloudflare R2: ファイル保存（画像など）

ログイン・セキュリティ（🚨 他人分混入事故対策統合）​

  • Firebase Authentication: ユーザーログイン機能
  • Cloudflare Access: 管理画面の入場制限
  • App Check: 悪いボットを防ぐ
  • JWT: API利用時の身分証明
  • 🚨 EXIF UID埋め込み: 写真にFirebase UIDを見えない形で記録
  • 🚨 SHA-256ハッシュ: 写真の改ざんを検知する仕組み
  • 🚨 三点検証システム: Order ID・Customer ID・Firebase UIDの照合
  • 🚨 セキュリティインシデント管理: 異常検知時の自動対応

外部サービス連携​

  • Shopify Storefront API: 商品表示・カート・決済
  • Shopify Admin API: 注文・お客様管理
  • Shopify Webhooks: 注文・決済の通知

🔄 データの流れ（Claude Code開発者向け）​

「システム内でデータがどのように流れるかを図で説明します」

1. ユーザー認証フロー​

sequenceDiagram
    participant User as User
    participant FE as Frontend
    participant BFF as BFF
    participant Firebase as Firebase Auth
    participant Shopify as Shopify

    User->>FE: Login
    FE->>Firebase: Auth
    Firebase-->>FE: JWT
    FE->>BFF: API Call + JWT
    BFF->>BFF: JWT Verify
    BFF->>Shopify: Get Customer
    Shopify-->>BFF: Customer Data
    BFF-->>FE: Auth Response

2. 注文フロー（🚨 他人分混入事故対策 + Queue System統合）​

sequenceDiagram
    participant User as User
    participant FE as Frontend
    participant BFF as BFF
    participant Queue as Cloudflare Queue
    participant Worker as Queue Worker
    participant Shopify as Shopify
    participant R2 as Cloudflare R2
    participant D1 as Cloudflare D1
    participant Security as Security Service

    User->>FE: Select Photo & Product
    FE->>BFF: Photo Upload Request
    BFF->>R2: Generate Signed URL
    FE->>R2: Upload Photo
    
    Note over BFF,Security: 🚨 UID Embedding (Checkpoint 1)
    BFF->>Security: Embed Firebase UID in EXIF
    Security->>R2: Update Photo with UID
    Security->>D1: Record Photo with Hash
    Security-->>BFF: UID Embedding Complete
    
    User->>FE: Create Order
    FE->>BFF: Order Request + Verification Data
    
    Note over BFF,Security: 🚨 Triple Check (Checkpoint 2)
    BFF->>Security: Verify Triple Match
    Security->>Security: Check Order ID + Customer ID + Firebase UID
    alt Triple Check Failed
        Security-->>BFF: Verification Failed
        BFF-->>FE: Order Rejected
    else Triple Check Passed
        Security-->>BFF: Verification Passed
        
        Note over BFF,Queue: Queue System (API制限対策)
        BFF->>D1: Save Order (status: queued, verified: true)
        BFF->>Queue: Enqueue VERIFIED_ORDER
        BFF-->>FE: Order Queued (<2s)
        
        Queue->>Worker: Process Verified Order
        
        Note over Worker,Security: 🚨 Factory Verification (Checkpoint 3)
        Worker->>Security: Pre-print Verification
        Security->>R2: Extract All Photo UIDs
        Security->>Security: Batch Verify All Photos
        alt Any Photo UID Mismatch
            Security-->>Worker: SECURITY ALERT
            Worker->>D1: Mark Order as Quarantined
            Worker->>FE: Security Incident Notification
        else All Photos Verified
            Security-->>Worker: All Photos Verified
            Worker->>Shopify: Create Order (40req/min safe)
            Shopify-->>Worker: Order Confirmation
            Worker->>D1: Update Order Status
            Worker->>R2: Prepare Print Data
            
            Note over Worker,FE: Normal Flow Continues
            Worker->>FE: Order Processing Complete
        end
    end

3. 🚨 他人分混入事故対策システム詳細フロー​

graph TB
    subgraph "Checkpoint 1: Photo Upload"
        A1[User Uploads Photo] --> A2[Generate Firebase UID]
        A2 --> A3[Embed UID in EXIF UserComment]
        A3 --> A4[Calculate SHA-256 Hash]
        A4 --> A5[Store in R2 + Record in D1]
    end
    
    subgraph "Checkpoint 2: Order Creation"
        B1[User Creates Order] --> B2[Extract Order Data]
        B2 --> B3{Triple Check}
        B3 -->|Order ID Match?| B4{Customer ID Match?}
        B4 -->|Firebase UID Match?| B5[All Verified ✅]
        B3 -->|Fail| B6[Reject Order ❌]
        B4 -->|Fail| B6
        B5 --> B7[Queue for Processing]
    end
    
    subgraph "Checkpoint 3: Factory Processing"
        C1[Factory Receives Order] --> C2[Extract All Photo UIDs]
        C2 --> C3[Verify Each Photo UID]
        C3 --> C4{All UIDs Match Expected?}
        C4 -->|Yes| C5[Start Printing ✅]
        C4 -->|No| C6[SECURITY ALERT ❌]
        C6 --> C7[Quarantine Order]
        C6 --> C8[Notify Security Team]
    end
    
    A5 --> B1
    B7 --> C1
    
    style B6 fill:#ff6b6b
    style C6 fill:#ff6b6b
    style C7 fill:#ff6b6b
    style B5 fill:#4caf50
    style C5 fill:#4caf50

🏛️ システム設計の基本ルール（Claude Code開発）​

「システムを作るときに守る大切なルールを説明します」

1. 役割分担（それぞれが専門の仕事をする）​

  • ユーザー画面: 見た目と使いやすさに専念
  • サーバー: ビジネスロジックとAPI連携
  • 外部サービス: 専門機能を提供

2. セキュリティ最優先（🚨 他人分混入事故対策強化）​

  • 認証: すべてのAPIで身分確認が必要
  • 権限: ブランド・権限レベルで制御
  • 監査: すべての操作を記録
  • 🚨 写真セキュリティ: Firebase UIDを各写真に埋め込み、改ざん不可能にする
  • 🚨 三点チェック: 注文時・決済時・印刷前の3回の本人確認
  • 🚨 事故防止: 他人の写真が間違って配送される事故を99.9%防ぐ

3. 拡張しやすさ​

  • 自動スケール: アクセスが増えても自動で対応
  • Queue System: API制限を自動的に解決し、429エラーを完全撲滅
  • モジュール設計: 部品を組み合わせる設計
  • 新サービス: 設定だけで新ブランドを追加可能

4. 運用のしやすさ​

  • 監視: システムの状態を常に確認
  • ログ: エラーが起きたら原因を追跡
  • デプロイ: コードの更新を自動化

🚀 段階的な開発計画（Claude Code実装）​

「どの順番でシステムを作っていくかの計画です」

フェーズ1: 最初のバージョン（MVP）​

  • 基本的な写真印刷サービス
  • 猫向けのWebサイトとスマホアプリ
  • 工場システムの基礎

フェーズ2: 機能を増やす​

  • いろいろな商品を追加
  • 犬向けサービスを開始
  • 写真編集機能を向上

フェーズ3: サービスを広げる​

  • 日本画印刷サービスを追加
  • 他の言語にも対応
  • パートナー企業との連携

詳細な設計については各セクションをご参照ください。