共通仕様 on 設計書

アーキテクチャ図

Mon, 01 Jan 0001 00:00:00 +0000

アーキテクチャ図#

概要#

本システムの全体構造、モノレポ内の各パッケージの責務、およびそれらの依存関係を定義する。本システムはモノレポ構成を採用し、関心の分離（SoC）を徹底する。

レイヤー構造図#

graph TD
 subgraph Apps ["apps/ (アプリケーション層)"]
 Frontend[frontend: React / React Router]
 Backend[backend: Hono / Bun]
 end

 subgraph Packages ["packages/ (共通基盤・ドメイン層)"]
 UI[ui: shadcn/uiベース共通コンポーネント]
 API[api: Orval 生成 Client]
 Domain[domain: ビジネスロジック・Entity/Policy]
 DB[db: Prisma/Repository]
 Infra[infra: Terraform/AWS設定]
 Shared[shared: Logger/Config/TraceID]
 end

 %% 依存関係
 Frontend --> UI
 Frontend --> API
 Frontend --> Shared
 
 Backend --> Domain
 Backend --> DB
 Backend --> Shared
 
 Domain --> DB
 Domain --> Shared
 
 DB --> Shared
 
 API -. "OpenAPIから生成" .-> Backend

各パッケージの責務#

apps/frontend: UI/UXの構築。React Routerによるルーティング、TanStack Queryによる状態管理。
apps/backend: HonoによるAPIエンドポイント。ミドルウェア（CORS, Logger, TraceID）の適用。
packages/domain: ビジネスロジックの中核。Entity, Value Object, Domain Service, およびポリシーの強制。
packages/db: データアクセス層。Prisma Clientを用いたデータベース操作、Repositoryパターン。
packages/ui: デザインシステムに基づく共通UIコンポーネント群。
packages/api: OpenAPI (specs/api) から生成されたフロントエンド用APIクライアント。
packages/infra: TerraformによるAWSリソース（S3, CloudFront, Lambda等）のコード化。
packages/shared: trace_id (UUID v4)、Pinoによる構造化ロガー、共通設定等の横断的関心事。

システム構成図

Mon, 01 Jan 0001 00:00:00 +0000

システム構成図#

概要#

本システムのデプロイメント環境および AWS インフラストラクチャの構成を定義する。

インフラ構成図#

使用サービス#

サービス名	役割・用途	スペック・設定	月額料金（円）	補足
Amazon CloudFront	CDN / SPA配信 / APIルーティング	価格クラス100	約1,500円	エッジでのキャッシュ、HTTPS終端、WAF連携
Amazon S3 (Static Assets)	フロントエンド(SPA)ホスティング	Standard Storage, 5GB保存	約500円	HTML / JS / CSS 等の静的ファイル配信
Amazon S3 (Image Storage)	画像ストレージ	Standard Storage, 20GB保存	約500円	アップロード画像の実体保存（Presigned URL方式）
API Gateway	APIエンドポイント管理	REST API, 10万リクエスト/月	約300円	Lambda Proxy統合、レート制限、認証
AWS Lambda (Hono / Bun)	APIバックエンド	128MB, 0.5秒平均, 10万実行/月	無料	サーバーレス実行環境。Prisma ORMによるDB操作
Amazon RDS (PostgreSQL)	マネージドデータベース	db.t3.micro, Single-AZ構成	約4,000円	画像のメタデータ・管理情報の永続化
AWS WAF	Webアプリケーションファイアウォール	Web ACL, 基本料金	約5,000円	レート制限、IP制限、SQLi/XSS等の攻撃防御
AWS Secrets Manager	秘密情報管理	標準, 5シークレット	約200円	DB認証情報、APIキー等のセキュアな保管
Amazon CloudWatch Logs	ログ管理	標準, 5GBログ	約750円	Pinoによる構造化ログ(JSON)の収集・蓄積
Amazon CloudWatch Alarms	監視・アラート	5個アラーム	約150円	メトリクス監視に基づいた異常検知・通知
AWS X-Ray	分散トレーシング	標準, 10万トレース	約100円	リクエストの追跡、パフォーマンスボトルネックの可視化
NAT Gateway	ネットワーク変換	1AZ, 10GB転送/月	約500円	プライベートサブネットからインターネットへの外部通信
Internet Gateway	VPCの出口	標準	無料	VPCとインターネット間の通信を可能にするゲートウェイ
合計	-	-	約8,000円	個人開発想定（月1,000ユーザー未満）

ネットワーク・セキュリティ#

HTTPS: 全通信は SSL/TLS で暗号化される。
CORS: S3 バケットの設定により、特定のオリジンからの Direct Upload のみを許可する。
VPC (Virtual Private Cloud): RDS 等のバックエンドリソースはプライベートサブネット内に配置し、不必要な外部露出を避ける（Terraform にて定義）。

セキュリティ設計指針

Mon, 01 Jan 0001 00:00:00 +0000

セキュリティ設計指針#

1. 基本方針#

API定義書（OpenAPI等）で定義された制約を厳格に適用し、脆弱性の混入を未然に防ぐ。

2. 認証・認可 (Authentication & Authorization)#

認証: MVPフェーズでは実施しない。将来的にIDP（Firebase Auth等）の導入を検討する。
認可: MVPフェーズでは実施しない。全てのリクエストを全権限ユーザーとして扱う。

3. 通信の保護#

全ての外部通信は TLS 1.2 以上（HTTPS）で暗号化する。
HSTS (HTTP Strict Transport Security) を有効化し、常時SSL化を強制する。

4. 入力値の検証とサニタイズ#

バリデーション: APIスペックに基づき、型、長さ、形式（正規表現）をリクエスト受領時に即座に検証する。
SQLインジェクション対策: ORMの利用を原則とし、生のSQLを記述する場合は必ず静的プリペアードステートメント（プレースホルダ）を使用する。
XSS対策: フロントエンド（React/Next.js等）のエスケープ機能を活用し、サーバー側でも適切なContent-Type（application/json等）を強制する。

5. データの暗号化#

保存時 (At Rest): データベースおよびオブジェクトストレージ（S3等）の暗号化を有効にする。
機密情報: APIキーやパスワード等は、暗号化した状態で環境変数またはシークレット管理ツールで管理する。

6. 秘匿情報の管理#

ソースコード内にパスワードやAPIキーを直接記述（ハードコード）することを厳禁とする。
.env.example を提供し、実際の値はシークレット管理サービスから動的に取得する。

ログ設計指針

Mon, 01 Jan 0001 00:00:00 +0000

ログ設計指針#

1. 出力形式#

ログの集約と解析を容易にするため、全てのログを JSON形式 で標準出力（stdout）に出力する。

2. ログレベル#

レベル	説明
FATAL	システム停止を伴う致命的なエラー。即時通知対象。
ERROR	継続は可能だが、期待しない動作が発生したエラー。要調査。
WARN	異常ではないが、リトライが発生した際やリソース不足の予兆など。
INFO	業務上の重要なイベント（ファイルアップロード完了等）。
DEBUG	開発時のデバッグ情報。本番環境では出力しない。

3. 共通ログ項目#

全てのログには以下のフィールドを必須または推奨で含める。

timestamp: ISO8601形式の時刻
level: ログレベル
trace_id: リクエスト間を横断して追跡するためのユニークなID（相関ID）
request_id: 単一操作を識別するためのユニークなID（冪等性制御・キャンセル用）
user_id: ユーザー識別子（MVPでは対象外とし、nullまたは固定値を出力する）
message: ログの内容（人間が読める形式）
context: 関連する補足データ（メタデータ）

4. 追跡可能性（Observability）#

モノレポ内の各サービス間で X-Trace-Id ヘッダーを伝播させ、フロントエンドからバックエンドまでの処理を単一のトレースIDで追跡可能にする。
X-Request-Id ヘッダーも併せて伝播させ、単一操作のログを特定して追跡可能にする。

5. ログ出力の禁止事項 (PIIの保護)#

以下の情報は、セキュリティおよびプライバシー保護のため、ログに出力してはならない。

パスワード、アクセストークン、シークレットキー
クレジットカード情報
個人情報（氏名、生年月日、住所、電話番号等）を直接特定できる情報
- 必要がある場合はハッシュ化またはマスキング処理（例: k****@example.com）を行う。

6. ログの保存とモニタリング#

保存期間: 運用要件に基づき、30日間（またはそれ以上）を標準とする。
監視: ERROR以上のログが発生した場合、Slack等のチャットツールへ通知を行う。

運用設計指針

Mon, 01 Jan 0001 00:00:00 +0000

運用設計指針#

概要#

本システムの運用における監視・障害対応・ログ管理の方針を定義する。

監視#

監視対象#

対象	監視内容	ツール
バックエンド (Lambda)	エラー率、レイテンシ、タイムアウト	CloudWatch Metrics
S3	アップロード成功率、4xx/5xxエラー	CloudWatch Metrics
DB (RDS)	接続数、クエリレイテンシ、ストレージ使用量	CloudWatch Metrics
ログ	エラーログの検出	CloudWatch Logs Insights

アラート基準（目安）#

条件	閾値	対応
バックエンドエラー率	1% 超	即時調査
アップロード成功率	99% 未満	即時調査
Lambda タイムアウト	連続3回以上	即時調査

障害対応#

調査手順#

CloudWatch Logs Insights で trace_id をキーに横断検索する。
特定の操作に問題がある場合は request_id で絞り込んで検索する。
フロントエンド → バックエンド → S3 → DB の順にログを追跡する。
エラー発生箇所を特定し、原因を切り分ける。

ログ検索クエリ例#

セッション全体の調査（trace_id）#

fields @timestamp, @message, request_id
| filter trace_id = "<対象のtrace_id>"
| sort @timestamp asc

特定操作の調査（request_id）#

fields @timestamp, @message, level
| filter request_id = "<対象のrequest_id>"
| sort @timestamp asc

エラー発生時の調査#

fields @timestamp, @message, level, error_code
| filter trace_id = "<対象のtrace_id>" and level = "ERROR"
| sort @timestamp desc

バックアップ・リカバリ#

対象	方針
RDS	自動バックアップ（保持期間: 7日）
S3	バージョニング有効化（誤削除対策）

デプロイ#

GitHub Actions による CI/CD で main ブランチへのマージをトリガーに自動デプロイする。
デプロイ前にAPIテスト・E2Eテストが通過していることを必須とする。
ロールバックは直前の Lambda バージョンへの切り戻しで対応する。

共通仕様 on 設計書

アーキテクチャ図

アーキテクチャ図#

概要#

レイヤー構造図#

各パッケージの責務#

システム構成図

システム構成図#

概要#

インフラ構成図#

使用サービス#

ネットワーク・セキュリティ#

セキュリティ設計指針

セキュリティ設計指針#

1. 基本方針#

2. 認証・認可 (Authentication & Authorization)#

3. 通信の保護#

4. 入力値の検証とサニタイズ#

5. データの暗号化#

6. 秘匿情報の管理#

ログ設計指針

ログ設計指針#

1. 出力形式#

2. ログレベル#

3. 共通ログ項目#

4. 追跡可能性（Observability）#

5. ログ出力の禁止事項 (PIIの保護)#

6. ログの保存とモニタリング#

運用設計指針

運用設計指針#

概要#

関連ドキュメント#

監視#

監視対象#

アラート基準（目安）#

障害対応#

調査手順#

ログ検索クエリ例#

セッション全体の調査（trace_id）#

特定操作の調査（request_id）#

エラー発生時の調査#

バックアップ・リカバリ#

デプロイ#