コードベースアーキテクチャ概要¶

項目	内容
対象読者	受入先の開発担当、保守担当、障害一次切り分け担当
目的	実行構成・コード配置・参照先を短時間で把握し、引き継ぎ後の保守開始を迷わせない
この文書の役割	納品/引き継ぎ向けの俯瞰資料。詳細実装は関連リンク先を参照
要件の正本	業務要件・商流ルール・運用要件は必ず docs/specifications/index.md を起点に確認

この文書の位置づけ¶

本書は、受入側が「このシステムは何で構成され、どこを見れば保守できるか」を把握するための入口です。

背景と対象範囲: プロジェクト背景と全体像
実装詳細ポータル: 03. 実装仕様ポータル
詳細なアーキテクチャ設計: システムアーキテクチャ設計書
日常運用・保守 runbook: システム保守ガイド
引き継ぎ全体の補助資料: 技術引き継ぎ書

本書では「何がどこにあるか」を優先して説明します。業務仕様の正否判断は本書ではなく、docs/specifications/ 配下の原資料を正本としてください。

この文書を読んだ直後の次の一歩¶

技術引き継ぎ書で権限移管と確認順を押さえる
プロジェクト背景と全体像で業務背景を確認する
03. 実装仕様ポータルから実装詳細の入口を辿る
保守・サポート計画書で窓口・応答条件・対象範囲を確認する
システム保守ガイドで運用 runbook の入口を押さえる

handover / maintenance / contract の役割分担¶

文書群	主な役割	まず確認すること
`handover/`	構成理解、参照先整理、権限移管の確認	どこを見ると保守を始められるか
`maintenance/`	日常運用、障害一次対応、バックアップ/復旧	何か起きたとき最初にどの手順を開くか
`04-project-management/maintenance-support-plan.md`	契約条件、窓口、応答条件、対象範囲	どこまでが保守契約の範囲か
`03-implementation/`	実装・配備・監視の技術詳細	深掘り先の正本はどこか

1. システムコンテキストと主な責務¶

このプロジェクトは、Storefront と Vendure Server を中心に、BtoB EC の業務ルールを Vendure プラグインで拡張した構成です。顧客向け画面、運用用ダッシュボード、外部連携、監視面が分かれています。

flowchart TB
  customer[顧客]
  ops[運用担当]

  storefront[Storefront<br/>apps/storefront<br/>Cloudflare Workers / Vite]
  dashboard[Vendure Dashboard / React Dashboard<br/>Cloudflare Workers]
  vendure[Vendure Server<br/>apps/vendure-server<br/>Fly.io nrt]

  pg[(PostgreSQL<br/>Fly.io app)]
  redis[(Redis<br/>Fly.io dedicated app)]
  r2[Cloudflare R2]
  kv[Cloudflare KV<br/>メンテナンス状態]
  wp[WordPress CMS]
  smile[SMILE]
  payment[決済サービス]
  mail[メール配送]
  sentry[Sentry]
  uptime[Uptime Kuma / Sentry Uptime]

  customer --> storefront
  ops --> dashboard
  storefront --> vendure
  dashboard --> vendure
  storefront -. maintenance flag .-> kv
  vendure --> pg
  vendure --> redis
  vendure --> r2
  vendure --> wp
  vendure --> smile
  vendure --> payment
  vendure --> mail
  storefront --> sentry
  vendure --> sentry
  dashboard --> sentry
  uptime --> storefront
  uptime --> vendure
  uptime --> wp

コンポーネント別の見方¶

領域	主な責務	まず見る場所	こんなときに使う
Storefront	顧客向け画面、認証導線、商品検索、注文導線、CMS 表示	`apps/storefront/` / frontend/index.md	画面不具合、表示差分、メンテナンス切替、Cloudflare Workers 側の問題を追うとき
Vendure Server	GraphQL API、注文/顧客/価格/配送/同意/連携の中核処理	`apps/vendure-server/` / system-architecture.md	API 障害、バッチ、マイグレーション、環境差異を確認するとき
Vendure プラグイン群	BtoB 固有の業務拡張を機能別に分離	`packages/plugins/` / vendure-plugins/index.md	商流ルール、SMILE 連携、同意取得、配送計算、可視性制御の所在を探すとき
共有パッケージ	ドメインモデル、契約、UI、共通設定/ユーティリティ	`packages/`	実装の重複箇所や型の正本を探すとき
運用/監視	監視設定、runbook、バックアップ、checked-in monitor 定義	`docs/05-delivery/maintenance/` / `observability/`	障害一次対応、監視設定、保守引き継ぎを行うとき

バージョン管理についての注記:
このプロジェクトはモノレポ構成であり、ルート全体の version は release-please、managed package (ritsubi-storefront / ritsubi-vendure-server) の version は custom managed changeset workflow で管理されています。ルートの package.json と各アプリの version 番号は必ずしも一致しません。

2. 現行のデプロイ / ランタイム構成¶

本番・ステージングの基本トポロジ¶

Surface	現行ランタイム	主な根拠	保守時の着眼点
Storefront	Cloudflare Workers（Vite SPA）	`apps/storefront/wrangler.toml`, `apps/storefront/worker.js`, `apps/storefront/scripts/cloudflare-deploy.mjs`	Worker 環境、KV binding、環境別 deploy（production / staging / preview / mock）
Vendure Server	Fly.io（Tokyo `nrt`）	`apps/vendure-server/fly.toml`, `fly.staging.toml`	`/health`、`release_command` による migration、`app` / `worker` process group、Fly secrets
Vendure Dashboard / React Dashboard	Cloudflare Workers	`apps/vendure-server/package.json` の `dashboard:deploy*`、`apps/vendure-server/wrangler.jsonc`	`vendure-dashboard` / `vendure-dashboard-staging`、`VITE_ADMIN_API_URL`、Sentry browser 側
PostgreSQL	Fly.io 上の専用 app	deployment-guide.md	接続情報、マイグレーション、バックアップ/復旧
Redis	Fly.io 上の専用 Redis app	deployment-guide.md	session / cache / queue 経路、環境ごとの接続先
WordPress CMS	VPS（Webarena Indigo）	system-architecture.md	CMS 側の公開状態、WPGraphQL、キャッシュ反映

環境別の読み分け¶

本番/ステージングのアプリ名確認
Vendure は ritsubi-ecommerce / ritsubi-ecommerce-staging、Storefront は ec-storefront 系、Dashboard は Cloudflare Workers vendure-dashboard / vendure-dashboard-staging を起点に確認します。
Storefront の緊急停止
メンテナンス状態の正本は Cloudflare KV です。詳細は Storefront メンテナンス運用 Runbook と補足仕様を参照してください。
Vendure のデプロイ
Fly.io deploy 時に release_command = "node dist/src/index.js migration" が設定されているため、アプリ更新と migration の関係を引き継ぎ時に必ず共有してください。あわせて Fly 側は app / worker process group を持ち、production は canary、staging は rolling で deploy されます。
Secrets の正本
ローカル運用は just と AWS Secrets Manager を優先し、ホスティング先には必要に応じて同期します。.env を運用正本にしない前提です。

環境を見分ける最小メモ¶

環境	主な見方	保守時の着眼点
production / staging	受入・運用の主対象。Storefront は Cloudflare Workers、Vendure / PostgreSQL / Redis は Fly.io を起点に確認	URL、`/health/live`、`/health/ready`、`/version`、deploy 導線、権限移管
preview / mock	Storefront の Cloudflare Workers deploy target として分離運用	production / staging と namespace や cache 方針が異なる前提で確認
local	`just` と AWS Secrets Manager を前提に起動する保守作業の入口	`.env` を運用正本にせず、ローカル再現と修正確認のために使う

外部依存の整理¶

依存先	役割	どこを見るか
Cloudflare Workers / KV / R2	Storefront 実行、Dashboard 配信、メンテナンス状態、オブジェクト保管	`apps/storefront/`, `apps/vendure-server/wrangler.jsonc`, `docs/03-implementation/infrastructure/`
Fly.io	Vendure、PostgreSQL、Redis の実行基盤	`apps/vendure-server/fly*.toml`, `docs/03-implementation/infrastructure/deployment-guide.md`
SMILE	顧客/受注などの外部業務連携	SMILE連携
WordPress CMS	コンテンツ供給	integration/index.md / wp-cms-integration.md
決済サービス	決済処理	`docs/specifications/` と payment-handlers.md
Sentry	エラー追跡、監視、アラート	monitoring-operations.md

監視・通知の自動化（Sentry / Uptime Kuma）¶

監視設定は以下の JSON ファイル群で管理し、observability/external-monitor-endpoints.json を正本としてスクリプトで自動適用します。

External Monitor Endpoint Catalog: observability/external-monitor-endpoints.json
scripts: scripts/ops/check-external-monitor-endpoints.mjs, scripts/ops/sentry-uptime-monitors.mjs, scripts/ops/uptime-kuma-monitors.mjs
役割: 外形監視対象 endpoint の共通正本。Sentry Uptime / Uptime Kuma 向け monitor 定義を runtime に組み立て、just monitor-endpoints-check で手動確認にも使います。
Sentry Workflow Alerts: observability/sentry-workflow-alerts.json
script: scripts/ops/sentry-workflow-alerts.mjs
役割: production での重大障害や依存サービス（Vendure 等）のスパイクを Slack #vendure-alerts へ通知します。
Sentry Uptime Apply
script: scripts/ops/sentry-uptime-monitors.mjs
役割: shared catalog から Storefront readiness / Vendure readiness / Vendure schema drift の monitor 定義を構築し、Sentry 上で継続監視（5分間隔）します。
Uptime Kuma Apply
script: scripts/ops/uptime-kuma-monitors.mjs
役割: shared catalog から Sentry とは独立した watchdog として、Storefront readiness / Vendure readiness / Vendure schema drift / WordPress login を監視します。

現行の継続監視の正式導線は Sentry Uptime / Uptime Kuma / GitHub Actions fallback です。observability/ 配下の Grafana / Prometheus / Loki 関連ファイルは、将来導入用テンプレートや補助定義を含みます。日常の障害一次切り分けは、まず監視・運用設計書を起点にしてください。

これらの自動化により、SaaS UI 上での手動設定に依存せず、リポジトリ管理された閾値と通知先を維持しています。詳細な運用手順は監視・運用設計書を参照してください。

3. モノレポ構造と主要ディレクトリ¶

このリポジトリは Nx + pnpm workspace で構成されます。納品・引き継ぎの観点では、まず apps / packages / infra / observability / docs / tests / scripts の役割を押さえれば十分です。

flowchart TD
  root[repo root]

  root --> apps[apps/]
  root --> packages[packages/]
  root --> infra[infra/]
  root --> docs[docs/]
  root --> observability[observability/]
  root --> tests[tests/]
  root --> scripts[scripts/]

ディレクトリ別の実務上の意味¶

パス	何があるか	いつ開くか
`apps/`	実行アプリの置き場。主に `storefront` と `vendure-server` を見る	顧客向け画面、API、ダッシュボード、実行設定の所在を確認するとき
`packages/`	共有コードの置き場。特に `plugins` が BtoB 拡張の中心	商流ルール、共通型、契約、再利用ロジックの所在を確認するとき
`infra/`	IaC とサーバー構成管理	インフラ変更や再構築時
`observability/`	checked-in monitor 定義、監視自動化、将来導入用テンプレート	監視移管、ログ経路の確認時
`docs/`	要件、設計、実装、運用、納品資料	正本・補助資料を横断参照するとき
`tests/`	横断テスト、統合確認の補助	回帰確認や受入観点の補助調査
`scripts/`	CI、運用、品質チェック支援	deploy や検証コマンドの実体確認

shared package の読み分け¶

packages/ を開いたときは、少なくとも次の責務分担を起点にすると迷いにくくなります。

パッケージ	主な責務	変更影響を考えるときの見方
`@ritsubi/config`	shared な設定責務、`env` / `defaults` / `spec` の技術定数	環境差異、設定値、runtime fallback の所在を確認するとき
`@ritsubi/contract`	システム間のデータ契約（GraphQL スキーマ定義・Zod バリデーションスキーマ）。runtime ロジックは持たない純粋な契約層	API や連携の入力/出力契約を確認するとき
`@ritsubi/domain`	業務不変条件、業務定数、依存ゼロのドメインロジック	商流ルールや業務前提の正本を探すとき
`@ritsubi/utils`	汎用 helper	業務責務ではなく共通処理を探すとき
`@ritsubi/ui`	shared UI primitive / wrapper	Storefront や React Dashboard で共通 UI を辿るとき

よく使う見方¶

画面や公開導線を追う: apps/storefront/
API や運用画面を追う: apps/vendure-server/
BtoB 固有ルールを追う: packages/plugins/
監視・運用の受け皿を探す: observability/ と docs/05-delivery/

4. 深掘りするときの参照順¶

最短ルート¶

本書で全体像を掴む
まず「何がどこにあるか」を把握する
引き継ぎ確認の順番を押さえる
技術引き継ぎ書
背景を掴む
プロジェクト背景と全体像
実装の全体ハブを見る
03. 実装仕様ポータル
ランタイム構成を深掘りする
システムアーキテクチャ設計書
機能ごとの所在を探す
Vendureプラグイン実装ガイド / Storefront 実装ガイド
契約条件と運用手順を確認する
保守・サポート計画書 / システム保守ガイド
要件の根拠に戻る
元仕様書ポータル

テーマ別リンク¶

知りたいこと	参照先
Storefront の実装方針	frontend/index.md
Vendure / Fly.io / Workers の構成	infrastructure/index.md
プラグインの責務一覧	vendure-plugins/overview.md
商流ルール・可視性・決済制御	vendure-plugins/index.md と `docs/specifications/`
SMILE 連携	smile-integration.md
CMS 連携	integration/index.md
監視・Sentry	monitoring-operations.md
バックアップ/復旧	backup-and-restore.md
日常保守	system-maintenance.md

5. 引き継ぎ時に最低限確認したい項目¶

以下は、受入側が「運用開始できる状態か」を確認するためのチェックポイントです。

ランタイム / アクセス¶

Cloudflare Workers（Storefront）・Cloudflare Workers（Vendure Dashboard / React Dashboard）・Fly.io（Vendure / PostgreSQL / Redis）へのアクセス権が受入側に移管されている
production / staging の対象アプリ・project 名が現行構成と一致している
Storefront のメンテナンス切替手順が Cloudflare KV 正本で理解されている

アプリ運用¶

Vendure deploy 時に migration が自動で実行される前提が共有されている
ローカル開発・保守作業で just と AWS Secrets Manager を使う運用が共有されている
packages/plugins 変更時にビルドが必要なこと、Dashboard 拡張変更時は Dashboard ビルド確認が必要なことが共有されている

監視 / 障害対応¶

Sentry の Storefront / Vendure / Dashboard 各 project の閲覧権限が移管されている
障害一次対応で参照する runbook（保守、バックアップ、KV 切替）が受入側に共有されている
ログ・監視基盤の所在（observability/ と関連ドキュメント）が把握されている

要件 / ドキュメント¶

業務要件の確認先が docs/specifications/ であることが共有されている
実装詳細・運用手順・受入資料の導線が docs/index.md と docs/05-delivery/index.md から辿れる
technical-handover.md、本書、保守 runbook の役割分担が整理されている

6. 保守のための読み方ガイド¶

「顧客向け画面の不具合」から入る場合
apps/storefront/ → docs/03-implementation/frontend/ → 必要に応じて docs/specifications/
「価格・配送・同意・SMILE 連携」から入る場合
packages/plugins/ → docs/03-implementation/vendure-plugins/ → docs/specifications/
「デプロイ/障害」から入る場合
apps/vendure-server/fly*.toml / apps/storefront/wrangler.toml → docs/03-implementation/infrastructure/ → docs/05-delivery/maintenance/
「要件差分の妥当性確認」から入る場合
先に docs/specifications/、次に docs/01-requirements/、最後に実装コードを確認

必要に応じて、本書を起点に「運用 runbook」「機能別プラグイン仕様」「原仕様」の順に降りていくと、引き継ぎ後の調査が最短になります。

コードベース アーキテクチャ概要¶