設計書

API一覧

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

API一覧#

ID	メソッド	パス	概要
api001	POST	`/images/presigned-url`	S3アップロード用の署名付きURLを発行する
api002	POST	`/images`	画像メタデータを登録する
api003	GET	`/images`	アップロード済み画像の名前リスト取得
api004	GET	`/images/:id`	画像の閲覧用URL（Presigned）取得

画面一覧

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

画面一覧#

ID	画面名	URI	概要
SCR001	画像アップロード画面	`/home`	画像の選択・アップロード・閲覧を行う単一画面

署名付きURL 発行

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

署名付きURL 発行#

ID#

api001-upload

エンドポイント#

メソッド	パス
POST	`/images/presigned-url`

概要#

S3アップロード用の署名付きURLを発行する。

リクエスト#

ボディ#

物理名	論理名	型	必須	説明
fileName	ファイル名	string	✓	アップロードするファイル名
fileSize	ファイルサイズ	number	✓	ファイルサイズ（バイト単位）
contentType	Content-Type	string	✓	MIMEタイプ

{
 "fileName": "string",
 "fileSize": "number",
 "contentType": "string"
}

バリデーション#

検証項目	条件	レスポンス	メッセージ	備考
ファイルサイズ	5MB 超	`400 Bad Request`	MSG-API-001
Content-Type	許可リスト外	`400 Bad Request`	MSG-API-002	許可 Content-Type: `image/jpeg` `image/png` `image/gif` `image/webp`
アップロード枚数上限	同一ユーザーが 5 枚以上保持	`409 Conflict`	MSG-API-003
レート制限	同一 IP から 1 分間に 10 回超	`429 Too Many Requests`	MSG-API-C001	共通仕様に準拠

Presigned URL 有効期限#

発行から 300 秒（5 分） 以内に PUT が完了しない場合 URL は無効となる。期限切れ時はクライアントが発行から再試行する。

API共通仕様

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

API共通仕様#

全APIエンドポイントに共通して適用される仕様を定義する。

ベースURL#

/api/v1

共通ヘッダー#

リクエスト#

ヘッダー名	必須	説明
X-Trace-ID	✓	トレーサビリティID（UUID v4）。フロントエンドで生成し全リクエストに付与する
X-Request-ID	✓	リクエスト識別ID（UUID v4）。フロントエンドで生成し、冪等性制御とキャンセルに使用する
Content-Type	△	リクエストボディがある場合は `application/json`

レスポンス#

ヘッダー名	説明
Content-Type	`application/json`

共通エラーレスポンス形式#

{
 "error": {
 "code": "string",
 "message": "string"
 }
}

フィールド名	説明	例
code	エラーコード	`INVALID_FILE_SIZE`
message	エラーメッセージ	`ファイルサイズが上限（5MB）を超えています`

共通ステータスコード#

コード	メッセージID	説明
429	MSG-API-C001	レート制限超過
500	MSG-API-C002	サーバー内部エラー

レート制限#

同一IPアドレスから1分間に10リクエストを超えた場合、429 Too Many Requests を返す。

トレーサビリティ#

ID の役割#

X-Trace-ID: セッション全体の横断的トレーサビリティを確保するためのID
X-Request-ID: 単一操作の冪等性制御とキャンセルに使用するID

実装方針#

フロントエンドは UUID v4 の X-Trace-ID を生成し、全リクエストヘッダーに付与する。
フロントエンドは UUID v4 の X-Request-ID を生成し、各操作のリクエストヘッダーに付与する。
バックエンドは両方のIDをリクエストヘッダーから受け取り、全レイヤのログに引き継ぐ。
X-Request-ID は冪等性チェックに使用し、DBには保存しない（メモリ内で管理）。
ログは Pino で構造化（JSON）出力し、CloudWatch Logs に集約する。

懸案事項#

認証・認可方式の未確定#

現状: API共通仕様に認証機構が定義されていない
影響:
- ユーザー識別が不可能で、アップロード枚数上限がグローバル制約となる
- アクセス制御ができず、全ユーザーが全画像にアクセス可能
- 監査証跡が不完全で、誰がどの操作を行ったか追跡不可
対応方針:
- JWTトークンまたはセッションベース認証の選定
- Authorizationヘッダーの必須化
- ユーザーIDの全リクエストへの引き継ぎ

Hono Middlewareへの影響#

現状: 認証ミドルウェアが未実装
影響:
- 各APIエンドポイントで個別に認証チェックが必要
- コード重複とメンテナンス性の低下
- セキュリティポリシーの統一が困難
対応方針:
- 認証ミドルウェアの共通化
- ユーザー情報のContextへの格納
- 認可エラーハンドリングの統一

トレーサビリティと認証の連携#

現状: trace_idのみでユーザー情報が紐づかない
影響: ユーザー単位の障害調査や監査が困難
対応方針:
- trace_idとuser_idの両方をログに記録
- ユーザー操作のエンドツーエンド追跡を可能にする

TBD#

認証方式の技術選定#

JWTトークン方式:
- メリット: ステートレス、スケーラビリティ高、SPA親和性
- デメリット: トークン失効・リフレッシュ処理の複雑化
セッション方式:
- メリット: 実装シンプル、サーバー側制御容易
- デメリット: ステートフル、スケーラビリティ制約
選定基準: セキュリティ要件、運用要件、パフォーマンス要件を考慮

ミドルウェアアーキテクチャ設計#

認証ミドルウェアの実装順序（レート制限→認証→認可）
エラーハンドリングの共通化
Context情報の型定義と引き継ぎ仕様

認可モデルの設計#

リソースベース認可: 画像所有者のみアクセス許可
ロールベース認可: 管理者権限の定義（将来拡張）
スコープ制御: 読み取り専用・書き込み専用アクセスの制御

セキュリティ強化項目#

トークン有効期限の最適設定
リフレッシュトークンの導入検討
CSRF対策の実装方針
APIキー管理（将来的な外部連携向け）

パフォーマンスへの影響評価#

認証チェックのオーバーヘッド測定
キャッシュ戦略との整合性
負荷テストでの性能検証

アップロード完了・メタデータ登録

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

アップロード完了・メタデータ登録#

ID#

api002-upload

エンドポイント#

メソッド	パス
POST	`/images`

概要#

S3への直接アップロード完了後、マジックナンバー検証を行いメタデータをDBに登録する。

リクエスト#

ボディ#

物理名	論理名	型	必須	説明
key	S3オブジェクトキー	string	✓	S3上の保存パス

{
 "key": "string"
}

バリデーション#

検証項目	条件	レスポンス	メッセージ	備考
S3ファイル存在	ファイルが存在しない	`404 Not Found`	MSG-API-005
マジックナンバー	許可フォーマット外	`422 Unprocessable Entity`	MSG-API-004	S3ファイルを削除（失敗時422）
S3削除失敗	削除操作のエラー	`500 Internal Server Error`	MSG-API-006	トランザクション不整合リスク
アップロード枚数上限	排他ロック取得後に5件以上	`409 Conflict`	MSG-API-003	SELECT FOR UPDATEで競合防止後にチェック

マジックナンバー検証#

S3上のファイルの先頭バイト列を読み取り、実際のMIMEタイプを検証する。ファイルサイズはS3 HeadObjectメタデータから取得し、クライアント送信値に依存しない。

フォーマット	マジックナンバー
JPEG	`FF D8 FF`
PNG	`89 50 4E 47 0D 0A 1A 0A`
GIF	`47 49 46 38`
WebP	`52 49 46 46` (offset 0) + `57 45 42 50` (offset 8)

レスポンス#

201 Created#

物理名	論理名	型	必須	説明
id	画像ID	string	✓	登録された画像のID
url	閲覧用URL	string	✓	画像の閲覧用URL

{
 "id": "string",
 "url": "string"
}

ステータスコード#

コード	説明
201	成功
404	S3上にファイルが存在しない
409	アップロード枚数上限超過（5件以上）
422	マジックナンバー検証失敗（S3ファイルを削除）
500	S3削除失敗またはDB登録失敗

内部処理シーケンス#

sequenceDiagram
 autonumber
 actor User
 participant Hono as Hono Middleware
 participant Domain as Domain Service
 participant S3 as S3 Client
 participant DB as Repository

 User->>+Hono: 完了通知 (key, request_id, trace_id )
 Hono->>Domain: 完了通知 (key, request_id, trace_id)
 Domain->>+S3: HeadObject（ファイルの存在確認・メタデータ取得）
 S3-->>-Domain: metadata (fileSize, ContentType, ...)
 Domain->>+S3: GetObject（先頭バイト取得）
 S3-->>-Domain: fileBytes
 Domain->>Domain: マジックナンバー検証
 alt 検証失敗
 Domain->>+S3: DeleteObject
 S3-->>-Domain: result
 Domain-->>Hono: Error (422 Unprocessable Entity)
 else 検証成功
 Domain->>+DB: SELECT FOR UPDATE（排他ロック取得 + 件数確認）
 DB-->>-Domain: currentCount
 alt 5件以上
 Domain-->>Hono: Error (409 Conflict)
 else 5件未満
 Domain->>+DB: INSERT メタデータ (id, key, fileSize, contentType, ...)
 DB-->>-Domain: result
 alt DB保存成功
 Domain-->>Hono: Success (201, id, url)
 else DB保存失敗
 Domain-->>Hono: Error (500 Internal Server Error)
 end
 end
 end
 Hono-->>-User: Response

懸案事項#

S3とDB間の分散トランザクション#

現状:

画面共通仕様

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

画面共通仕様#

トレーサビリティ#

使い分け#

ID	目的	生成場所	有効期間	主な用途
trace_id	横断的トレーサビリティ	Frontend (セッション開始時)	セッション全体	ログ集約・障害調査
request_id	操作的冪等性	Frontend (各操作開始時)	単一操作	重複実行防止・キャンセル

trace_id の生成と伝播#

用途: ユーザーセッション全体の追跡、横断的なログ検索
生成: アプリ初期化時に UUID v4 を一度だけ生成し、グローバル状態で保持
伝播: 全APIリクエストヘッダー X-Trace-ID に自動付与
可視化: 開発者ツールで表示し、障害調査時に CloudWatch Logs Insights で横断検索

request_id の生成と管理#

用途: 操作の重複防止、非同期処理のキャンセル、リトライ制御
生成: 各操作開始時に UUID v4 を都度生成（ファイルアップロード、API呼び出しなど）
管理: 操作単位でローカルに管理し、処理完了まで保持
冪等性: 同一操作の重複実行を防止するため、request_id を生成して管理
キャンセル対応: 非同期処理のキャンセル時に request_id を使用して処理を特定

プログレスバー#

アップロードプログレスバー#

stateDiagram-v2
 [*] --> Idle: アップロード開始
 Idle --> Uploading: ファイル選択
 Uploading --> Processing: アップロード完了
 Uploading --> Error: エラー発生
 Processing --> Success: 処理完了
 Processing --> Error: エラー発生
 Error --> Idle: リトライ or キャンセル
 Success --> Idle: 完了

プログレスバーの仕様#

表示条件: ファイルアップロード時、API リクエスト時
進捗表示: パーセンテージと残り時間を表示
キャンセル機能: ユーザーがいつでもキャンセル可能
エラー表示: エラー発生時に詳細メッセージを表示

懸案事項#

技術的懸案#

ブラウザ互換性: AbortController の IE サポート
ネットワーク切断: オフライン時の処理方針

UI/UX 懸案#

エラーメッセージ: ユーザーフレンドリーなエラー表現
アクセシビリティ: スクリーンリーダー対応

TBD#

機能仕様#

ファイルサイズ制限: 具体的な上限値の決定
同時アップロード数: 複数ファイル同時アップロードの制限
プレビュー機能: アップロード前の画像プレビュー要否

技術仕様#

CDN 対応: 静的アセットの配信戦略
PWA 対応: Service Worker の導入要否
監視体制: エラーログ収集方法

セキュリティ仕様#

CSP ポリシー: Content Security Policy の詳細
XSS 対策: 入力値検証の範囲
CSRF 対策: トークン管理方式

非同期処理の制御#

キャンセル機構

APIメッセージ一覧表

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

APIメッセージ一覧表#

APIレスポンスに含まれるエラーメッセージを管理する。{変数名} は動的に置換される。

共通メッセージ#

全APIで共通して使用するメッセージ。

メッセージID	ステータスコード	code	メッセージテンプレート	変数
MSG-API-C001	429	`RATE_LIMIT_EXCEEDED`	リクエスト数が上限（{limit}回/{window}）を超えました	`limit`: 上限回数（例: 10）、`window`: 時間窓（例: 1分）
MSG-API-C002	500	`INTERNAL_SERVER_ERROR`	サーバーエラーが発生しました	—

個別メッセージ#

メッセージID	ステータスコード	code	メッセージテンプレート	変数	発生条件
MSG-API-001	400	`INVALID_FILE_SIZE`	ファイルサイズが上限（{maxSize}）を超えています	`maxSize`: 上限サイズ（例: 5MB）	fileSize > 5,242,880 bytes
MSG-API-002	400	`INVALID_CONTENT_TYPE`	対応していないファイル形式です（許可形式: {allowedTypes}）	`allowedTypes`: 許可MIMEタイプ一覧（例: jpeg, png, gif, webp）	contentType が許可リスト外
MSG-API-003	409	`UPLOAD_LIMIT_EXCEEDED`	アップロード可能な枚数の上限（{maxCount}枚）に達しています	`maxCount`: 上限枚数（例: 5）	アップロード済み枚数 >= 上限
MSG-API-004	422	`INVALID_FILE_BINARY`	ファイルのバイナリ検証に失敗しました	—	マジックナンバー不一致
MSG-API-005	404	`FILE_NOT_FOUND_ON_S3`	S3上にファイルが存在しません	—	HeadObject で対象キーが見つからない
MSG-API-006	404	`IMAGE_NOT_FOUND`	指定された画像が存在しません（id: {id}）	`id`: リクエストされた画像ID	DBに対象IDが存在しない

画像一覧取得

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

画像一覧取得#

ID#

api003-upload

エンドポイント#

メソッド	パス
GET	`/images`

概要#

アップロード済み画像のメタデータ一覧（ID・ファイル名）を取得する。画像の実体（バイナリ・閲覧用URL）はここでは取得しない。ユーザーがリストから画像を選択した時点で api004-upload により個別取得する。

レスポンス#

200 OK#

物理名	論理名	型	必須	説明
id	画像ID	string	✓	登録された画像のID
fileName	ファイル名	string	✓	アップロードされたファイル名
createdAt	作成日時	string	✓	ISO-8601形式の作成日時

[
 {
 "id": "string",
 "fileName": "string",
 "createdAt": "iso-8601"
 }
]

ステータスコード#

コード	説明
200	成功（0件の場合は空配列）

内部処理シーケンス#

sequenceDiagram
 autonumber
 actor User
 participant Hono as Hono Middleware
 participant Domain as Domain Service
 participant DB as Repository

 User->>+Hono: 一覧取得リクエスト
 Hono->>+Domain: 一覧取得リクエスト
 Domain->>+DB: findAll()
 DB-->>-Domain: [{id, fileName, createdAt}]
 Domain-->>-Hono: Success
 Hono-->>-User: 200 OK

懸案事項#

ユーザーごとの絞り込み未実装#

現状: 全ユーザーの画像を返却している
影響: 他ユーザーの画像が見えてしまう、プライバシー問題
対応方針: 認証ミドルウェアから取得したユーザーIDで絞り込み

パフォーマンス問題#

現状: 全件取得でページネーションなし
影響: 画像数増加時のレスポンス悪化、メモリ消費
対応方針: ページネーションとキャッシュ導入

TBD#

並び順とソート機能#

作成日順のデフォルトソート
ファイル名順、サイズ順のソートオプション
昇順・降順の指定

検索機能拡張#

ファイル名の部分一致検索
メタデータによる検索（将来的な機能拡張）
タグによる絞り込み

画面メッセージ一覧表

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

画面メッセージ一覧表#

画面上に表示されるすべてのメッセージを管理する。{変数名} は動的に置換される。

共通メッセージ#

操作結果に応じて汎用的に使用するメッセージ。

メッセージID	種別	メッセージテンプレート	変数
MSG-UI-C001	成功	{target}を登録しました	`target`: 対象名（例: 画像）
MSG-UI-C002	成功	{target}を更新しました	`target`: 対象名
MSG-UI-C003	成功	{target}を削除しました	`target`: 対象名
MSG-UI-C004	エラー	通信エラーが発生しました。再度お試しください	—
MSG-UI-C005	エラー	サーバーエラーが発生しました。しばらくしてから再度お試しください	—

個別メッセージ#

メッセージID	種別	メッセージテンプレート	変数	発生条件
MSG-UI-001	エラー	対応していないファイル形式です	—	ファイル拡張子・MIMEタイプが許可リスト外
MSG-UI-002	エラー	ファイルサイズが上限（{maxSize}）を超えています	`maxSize`: 上限サイズ（例: 5MB）	ファイルサイズが上限超過
MSG-UI-003	エラー	アップロードがタイムアウトしました。再度お試しください	—	S3アップロード時のネットワークタイムアウト
MSG-UI-004	エラー	アップロードに失敗しました。URLの有効期限が切れている可能性があります	—	Presigned URL有効期限切れ
MSG-UI-005	エラー	ファイルアクセス権限がありません	—	S3アクセス権限エラー
MSG-UI-006	警告	最大アップロード数に達しました	—	アップロード上限到達時
MSG-UI-007	エラー	署名付きURLの取得に失敗しました。再度お試しください	—	Presigned URL取得レスポンスにuploadUrlまたはkeyが含まれない

画像アップロード画面

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

画像アップロード画面#

ID#

scr001-upload

種別	ドキュメント
要件	req001-upload
相互作用	ia001-upload
API	api001-upload / api002-upload / api003-upload / api004-upload

概要#

…

ユーザーがローカル端末から画像を選択・プレビューし、S3へアップロードする
アップロード済み画像のファイル名一覧を表示し、選択した画像をプレビュー閲覧できる

レイアウト#

遷移#

単一画面（画面遷移なし）

項目#

No	項目名	種類	説明	初期状態	制約	備考
1	画像選択ボタン	Button / Input	ローカルからファイル選択ダイアログを開く	活性	アップロード済み5枚時はDisabled	上限到達時は項目4に「最大アップロード数に達しました」を表示
2	選択画像プレビュー	Image	現在選択されている（未アップロード）画像のプレビュー	非表示	—	ファイル選択後に表示。アップロード完了後にクリア
3	アップロードボタン	Button	S3へのアップロードとDB登録を開始する	非活性	画像未選択時はDisabled	—
4	ステータスメッセージ	Text	成功・エラー・警告を表示する	空	—	アクション結果に応じて動的に更新
5	画像リスト	List	アップロード済みのファイル名を一覧表示する	画面表示時にDBから取得	—	画面初期表示時に api003 を呼び出す
6	ギャラリープレビュー	Image	リストで選択されたアップロード済み画像のプレビュー	非表示	—	項目5のファイル名クリック時に api004 で取得したURLを表示

アクション#

No	アクション名	トリガー	処理概要	期待結果	API	備考
1	初期表示	画面表示時（自動）	アップロード済み画像のメタデータ一覧を取得	項目5にファイル名リスト表示	api003	—
2	ファイル選択	画像選択ボタン押下	ファイル形式・サイズをクライアントバリデーション後、プレビューを生成	項目2にプレビュー表示、項目3を活性化	—	バリデーション違反時は項目4にエラー表示(MSG-UI-001/MSG-UI-002)
3	アップロード実行	アップロードボタン押下	Presigned URL取得 → S3アップロード → メタデータ保存	項目4に成功メッセージ(MSG-UI-C001)表示、項目5のリスト更新	api001 → api002	完了後にアクション5を実行。失敗時はMSG-UI-C004/MSG-UI-C005を表示
4	リスト項目選択	項目5のファイル名クリック	選択画像の閲覧用Presigned URLを個別取得して表示	項目6にプレビュー表示	api004	初期表示時は取得しない（遅延取得）
5	プレビュークリア	アップロード完了後（自動）	選択状態と項目2のプレビューをリセット	項目3を非活性化	—	アクション3の完了後に自動実行

バリデーション（クライアントサイド）#

アクション1（ファイル選択時）に実施する。違反時は項目4にエラーメッセージを表示し、リクエストを送信しない。

画像閲覧用URL取得

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

画像閲覧用URL取得#

ID#

api004-upload

エンドポイント#

メソッド	パス
GET	`/images/:id`

概要#

指定した画像IDに対応する閲覧用Presigned URLを取得する。

リクエスト#

パスパラメータ#

物理名	論理名	型	必須	説明
id	画像ID	string (UUID)	✓	閲覧したい画像のID

レスポンス#

200 OK#

物理名	論理名	型	必須	説明
url	閲覧用URL	string	✓	画像の閲覧用Presigned URL
expiresAt	有効期限	string	✓	URLの有効期限（ISO-8601形式）

{
 "url": "string",
 "expiresAt": "iso-8601"
}

ステータスコード#

コード	説明
200	成功
404	指定IDの画像が存在しない

内部処理シーケンス#

sequenceDiagram
 autonumber
 actor User
 participant Hono as Hono Middleware
 participant Domain as Domain Service
 participant DB as Repository
 participant S3 as S3 Client

 User->>+Hono: 閲覧URLリクエスト (id)
 Hono->>+Domain: 閲覧URLリクエスト (id)
 Domain->>+DB: findById(id)
 DB-->>-Domain: image (s3Key)
 Domain->>+S3: getSignedUrl (GetObject, s3Key, expires=3600)
 S3-->>-Domain: url
 Domain-->>-Hono: Success (url, expiresAt)
 Hono-->>-User: 200 OK

懸案事項#

アクセス権限の未実装#

現状: 画像IDさえ知っていれば誰でも閲覧可能
影響: 他ユーザーのプライベート画像にアクセス可能になる
対応方針: 画像所有者のみアクセス許可の認可チェック

TBD#

アクセス制御の細粒度化#

画像ごとの公開・非公開設定
特定ユーザーへのアクセス許可機能
一時的なアクセスURL発行

キャッシュ戦略#

CloudFrontによるCDNキャッシュ
閲覧URLのキャッシュ期間最適化
画像の最適化（リサイズ）とキャッシュ

ER図

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

ER図#

erDiagram
 images {
 string id PK "UUID v4"
 string file_name "ファイル名"
 int file_size "ファイルサイズ"
 string content_type "MIMEタイプ"
 string s3_key UK "S3上の保存パス"
 datetime created_at "作成日時"
 datetime updated_at "更新日時"
 }

アーキテクチャ図

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

テーブル定義書#

images テーブル#

テーブル情報#

項目	値
テーブル名	`images`
概要	アップロードされた画像のメタデータを管理する
スキーマ	public

カラム情報#

カラム名	型	NOT NULL	デフォルト	説明
id	VARCHAR(36)	✓	—	主キー（UUID v4）
file_name	VARCHAR(255)	✓	—	ファイル名
file_size	INTEGER	✓	—	ファイルサイズ（bytes）
content_type	VARCHAR(50)	✓	—	MIMEタイプ
s3_key	VARCHAR(512)	✓	—	S3上の保存パス
created_at	TIMESTAMP	✓	CURRENT_TIMESTAMP	作成日時
updated_at	TIMESTAMP	✓	CURRENT_TIMESTAMP	更新日時（自動更新）

インデックス情報#

インデックス名	カラム	種類	説明
images_pkey	id	PRIMARY KEY	主キーインデックス
images_s3_key_key	s3_key	UNIQUE	重複アップロード防止
images_created_at_idx	created_at	INDEX	一覧表示のソート用

制約情報#

制約名	種類	カラム	条件	説明
images_pkey	PRIMARY KEY	id	—	主キー制約
images_s3_key_key	UNIQUE	s3_key	—	S3パスの一意性

外部キー情報#

現バージョンでは外部キーなし。ユーザー管理機能追加時に user_id → users.id の外部キーを追加予定。

ログ設計指針

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

画像アップロード#

ID#

sec001-upload

概要#

画像アップロード時における脅威と、それに対する具体的な防御策を定義する。

セキュリティリスク分析#

1. ファイル形式偽装攻撃#

脅威: 悪意のある実行ファイルを画像ファイルとして偽装してアップロードされる

防御策:

バイナリ検証: ファイルの拡張子だけでなく、マジックナンバー（バイナリヘッダ）を読み取り、許可された画像形式であることを検証する
許可リスト: JPEG、PNG、WebPなど許可された画像形式のみを受け付ける
ファイル内容スキャン: アップロード後にウイルススキャンを実施する

2. 不正アクセスとデータ漏洩#

脅威: 認証されていないユーザーによる画像へのアクセスや第三者への漏洩

防御策:

署名付きURL: S3へのアップロード・ダウンロードには署名付きURLを使用する
有効期限制御: 署名付きURLの有効期限を厳格に管理する（アップロード用5分、閲覧用1時間）
最小権限原則: アップロードされたファイルはデフォルトで非公開とし、presigned URL経由のみ閲覧可能とする

3. リソース枯渇攻撃#

脅威: 大量のアップロードによるストレージ容量の枯渇や、サービス妨害

防御策:

サイズ制限: ファイルサイズを5MB以下に制限する
レート制限: IPアドレスまたはユーザーIDごとにアップロード回数を制限する（1分間に10回まで）
クォータ管理: ユーザーごとの総アップロード容量を制限する

4. 中間者攻撃#

脅威: 通信経路でのデータ改ざんや盗聴

防御策:

TLS強制: 全通信をHTTPS（TLS 1.2以上）に限定する
証明書検証: SSL/TLS証明書の厳格な検証を行う
HSTS: HTTP Strict Transport Securityを有効化する

セキュリティ要件#

1. 多層防御 (Defense in Depth)#

バイナリ検証: システムは、ファイルの拡張子だけでなく、マジックナンバー（バイナリヘッダ）を読み取り、許可された画像形式であることを検証しなければならない。
署名付きURL: S3 へのアップロードには署名付き URL を使用し、その有効期限は発行から 5分間 としなければならない。

2. 最小権限の原則#

S3 ACL: アップロードされたファイルはデフォルトで非公開とし、認可用 presigned URL を介してのみ閲覧可能とする。

3. リソース制限#

Size Limit: バックエンドは、署名付き URL 発行前にリクエストされたファイルサイズが 5MB 以下であることを厳密に検証しなければならない。
Rate Limit: IP アドレスまたはユーザー ID ごとに、一定時間内のアップロード回数を制限しなければならない（1分間に 10回まで等）。

4. 通信セキュリティ#

TLS強制: 全ての通信はHTTPS（TLS 1.2以上）でなければならない。
証明書検証: SSL/TLS証明書の有効性を検証しなければならない。

画像アップロード機能

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

画像アップロード機能#

ID#

infra001-upload

使用リソース#

リソース	用途
AWS S3	画像ファイルの保存

S3 バケット設定#

パブリックアクセス: Block Public Access を有効化し、直接公開を禁止する。
オブジェクトアクセス: Presigned URL 経由のみ許可（アップロード用 PUT・閲覧用 GET）。
暗号化: SSE-S3（サーバーサイド暗号化）を有効化する。
CORS: フロントエンドオリジンからの PUT のみ許可する。
ストレージクラス: Standard（頻繁アクセス向け）

{
 "CORSRules": [
 {
 "AllowedOrigins": ["https://<frontend-domain>"],
 "AllowedMethods": ["PUT"],
 "AllowedHeaders": ["Content-Type"],
 "MaxAgeSeconds": 300
 }
 ]
}

S3 ストレージクラスと料金#

ストレージクラス#

ストレージクラス	用途	特徴
S3 Standard	アクセス頻度の高い画像	頻繁アクセス、低レイテンシ

料金（東京リージョン、2024年3月時点）#

ストレージクラス	保存料金（GB/月）	リクエスト料金（GET/1,000回）	リクエスト料金（PUT/1,000回）
S3 Standard	¥23	¥0.43	¥5

ライフサイクルポリシー#

0日～30日: S3 Standard（アップロード直後）
30日～90日: S3 Standard-IA（アクセス頻度低下）
90日以降: S3 Glacier Instant Retrieval（アーカイブ）

Presigned URL#

種別	操作	有効期限
アップロード用	PutObject	300 秒（5 分）
閲覧用	GetObject	3600 秒（1 時間）

ネットワーク#

全通信は HTTPS（TLS 1.2 以上）。
Terraform にて定義する（packages/infra/）。

画像アップロード機能

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

画像アップロード機能#

ID#

ia001-upload

概要#

画像アップロード機能の相互作用設計を定義する

種別	ドキュメント
要件	req001-upload
UI	scr001-upload
API	api001-upload
API	api002-upload
API	api003-upload
API	api004-upload
インフラ	infra001-upload
セキュリティ	sec001-upload

ユースケース#

graph LR
 Actor((ユーザー))

 subgraph アップロード
 UC1[画像を選択してプレビューする]
 UC2[画像をアップロードする]
 end

 subgraph 閲覧
 UC3[アップロード済み画像の一覧をファイル名で確認する]
 UC4[ファイル名を選択して画像を閲覧する]
 end

 Actor --> UC1
 Actor --> UC2
 Actor --> UC3
 Actor --> UC4

シーケンス#

画像アップロード#

sequenceDiagram
 autonumber
 actor User as ユーザー
 participant FE as フロントエンド
 participant BE as バックエンド
 participant S3 as S3
 participant DB as DB

 User->>FE: ファイル選択
 FE->>FE: クライアントバリデーション
 FE->>FE: プレビュー表示

 User->>FE: アップロードボタン押下
 FE->>BE: api001-upload
 Note over FE,BE: X-Trace-ID ヘッダー付与

 BE->>BE: サーバーバリデーション
 BE->>S3: PutObject 署名付きURL生成
 S3-->>BE: uploadUrl
 BE-->>FE: uploadUrl, key

 FE->>S3: PUT uploadUrl（バイナリ直接送信）
 S3-->>FE: 200 OK

 FE->>BE: api002-upload
 BE->>S3: HeadObject（存在確認）
 BE->>BE: サーバーバリデーション
 BE->>DB: メタデータ保存
 DB-->>BE: 保存完了
 BE-->>FE: 201 Created（id, url）

 FE->>User: 成功メッセージ・リスト更新

画像閲覧#

sequenceDiagram
 autonumber
 actor User as ユーザー
 participant FE as フロントエンド
 participant BE as バックエンド
 participant DB as DB
 participant S3 as S3

 User->>FE: 初期表示
 FE->>BE: api003-upload
 Note over FE,BE: メタデータ（ID・ファイル名）のみ取得。画像実体は取得しない
 BE->>DB: 画像一覧取得
 DB-->>BE: [{id, fileName, createdAt}]
 BE-->>FE: リスト返却
 FE->>User: ファイル名リスト表示

 User->>FE: ファイル名クリック
 Note over FE,BE: 選択時に初めて画像実体（閲覧用URL）を取得
 FE->>BE: api004-upload
 BE->>S3: GetObject 閲覧用 Presigned URL 生成
 BE-->>FE: url
 FE->>User: プレビュー表示

画像アップロード機能

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

画像アップロード機能#

ID#

req001-upload

概要#

ユーザーがアプリケーションを介して画像ファイルをアップロードし、永続化・閲覧できる機能を提供する。

ビジネス要件#

ユーザーは画像を送信し、表示できる必要がある。
不適切なファイルのアップロードを防止し、システムの安定性を担保する。

As-Is#

なし

To-Be#

ユーザーがローカル端末から画像を選択し、クラウドストレージへアップロード・閲覧できる。
不正ファイルの混入を防ぎ、安全かつ安定したファイル管理基盤を持つ。

スコープ#

画像の選択・プレビュー・アップロード・閲覧
クライアント／サーバー双方でのバリデーション
S3 Presigned URL を用いた直接アップロード方式

ステークホルダー / ペルソナ#

発注者: システム開発の依頼者であり、最初の利用者
エンドユーザー: MVP段階では発注者のみを想定。将来的に一般ユーザーへの展開を想定

機能要件#

画像の選択とプレビュー#

ユーザーはローカル端末から画像ファイルを選択できる。
アップロード前に選択したファイルのプレビューを表示する。

画像のアップロード#

選択された画像をサーバー（S3）にアップロードする。
アップロード成功後、メタデータ（ファイル名、URL、サイズ等）をDBに保存する。

バリデーション#

ファイルサイズ制限: 最大 5MB。
対応フォーマット: JPEG, PNG, GIF, WebP。
MIMEタイプはバイナリヘッダ（マジックナンバー）で検証する。
クライアントサイドとサーバーサイドの両方で検証を行う。

アップロード済み画像の閲覧#

アップロード済みの画像はファイル名のリストとして表示される。
リストからファイル名を選択することで、その画像のプレビューを表示する。
通信量削減のため、初期表示時にすべての画像の実体を取得しない。

非機能要件#

可用性・スケーラビリティ#

大容量ファイルの転送によるバックエンドサーバーの負荷を避けるため、S3 Presigned URL（署名付きURL） を使用した直接アップロード方式を採用する。

セキュリティ#

マジックナンバーによる検証: 拡張子だけでなく、バイナリヘッダによるMIMEタイプ検証を行う。
署名付きURLの有効期限:
- アップロード用: 5分以内に制限する
- 閲覧用: 1時間以内に制限する
公開設定: アップロードされたファイルは適切なACL（またはPublic Access Block）を設定し、不要な公開を避ける。

トレーサビリティ#

アップロード処理全体に trace_id を付与し、フロントエンドからS3、バックエンド、DBまでのログを紐づけ可能とする。

前提条件・制約#

アップロード可能な画像数は最大 5枚とする。
1度の処理でアップロードできる画像数は 1枚とする。
ファイルストレージとして AWS S3 または互換ストレージを使用する。

MVP開発方針#

スコープ外#

ユーザー管理機能: ユーザー登録、認証、認可は実装しない
アクセス制御: 画像の所有者制限や権限管理は実装しない
プライバシー設定: 画像の公開・非公開設定は実装しない

理由#

MVP（Minimum Viable Product）として、まずは画像アップロード・表示の基本機能に集中し、ユーザー管理のような機能は後のバージョンで実装する。これにより早期に価値を提供しつつ、開発期間を短縮する。

運用設計指針

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 バージョンへの切り戻しで対応する。