docs: アーキテクチャドキュメントを追加

[TinyKitten]

• docs/architecture.md を新規作成
  • 4層構造（Domain/UseCase/Infrastructure/Presentation）の設計思想
  • データベース/gRPC/スキーマ更新時の注意点
  • 命名規則（Row構造体 vs Entity の区別）
  • キャッシュ戦略の判断理由（query.rs:169-265）
• README.md にドキュメントへの参照を追加
• technical_debt.md のアーキテクチャドキュメント不足を対応済みに更新

Closes #1350

🤖 Generated with Claude Code

Summary by CodeRabbit

リリースノート

• Documentation
  • アーキテクチャドキュメントを追加し、システム設計、レイヤー構成、技術スタック、データフロー、命名規約やキャッシュ戦略などを詳細に記載
  • テクニカルデブトのステータスを更新し、関連作業を完了済みとしてマーク、関連参照を明示
  • README に新しいドキュメント参照リンクを追加し、案内を改善

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

アーキテクチャドキュメントを新規追加し（docs/architecture.md）、READMEに参照リンクを追加、docs/technical_debt.mdで該当タスクを完了済みに更新しました。変更はドキュメントのみでコードや公開APIには影響しません。

Changes

コホート / ファイル(s)	変更概要
新規ドキュメント docs/architecture.md	StationAPIの4層クリーンアーキテクチャ（Presentation/UseCase/Infrastructure/Domain）、技術スタック（Rust 2021, tokio, PostgreSQL 15+, sqlx, gRPC/tonic, protobuf）、各層の設計ノート、データフロー、Row/Entity命名規則、キャッシュ戦略、DB設計・マイグレーション注意点などを日本語で詳細に追加
参照追加 README.md	Documentationセクションに docs/architecture.md へのリンクを新規追加
進捗更新 docs/technical_debt.md	技術的負債ドキュメントのステータスを更新し、アーキテクチャ関連項目を完了扱いに変更、該当ドキュメントへのリンクを追加（機能コードの変更なし）

Sequence Diagram(s)

（この変更はドキュメント追加/更新のみのため、シーケンス図は省略します。）

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10分

Possibly related PRs

• docs: 技術負債分析レポートを追加 #1348 — READMEやドキュメント周りの修正を含む同一領域のPR。docs/architecture.md作成依頼と関連。

Poem

🐰📜 アーキテクチャ、穴掘りして見つけた
四層に刻む設計の歌声
ROWがENTITYへ、道をつなぎ
ドキュメントは光、迷わぬ地図
ぴょんと渡る未来へ — お祝いだよ 🥕✨

Pre-merge checks

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	プルリクエストのタイトル「docs: アーキテクチャドキュメントを追加」は、変更の主要な目的（アーキテクチャドキュメントの追加）を明確かつ簡潔に要約しており、変更内容全体を適切に説明しています。
Linked Issues check	✅ Passed	プルリクエストは、リンク済みイシュー #1350 で要求されたすべてのコーディング関連要件を満たしています。docs/architecture.md の作成、README.md への参照追加、technical_debt.md の更新が完了しました。
Out of Scope Changes check	✅ Passed	すべての変更（docs/architecture.md の新規作成、README.md の更新、technical_debt.md の更新）は、リンク済みイシュー #1350 で定義された要件の範囲内です。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 61f091e and c60728e.

📒 Files selected for processing (1)

• docs/architecture.md

🧰 Additional context used

📓 Path-based instructions (1)

{docs/**/*.md,README.md}

📄 CodeRabbit inference engine (AGENTS.md)

For database, gRPC, or schema updates, add architectural notes under docs/ and synchronize README references to keep onboarding materials accurate

Files:

• docs/architecture.md

🧠 Learnings (9)

📓 Common learnings

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to {docs/**/*.md,README.md} : For database, gRPC, or schema updates, add architectural notes under `docs/` and synchronize README references to keep onboarding materials accurate

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to {docs/**/*.md,README.md} : For database, gRPC, or schema updates, add architectural notes under `docs/` and synchronize README references to keep onboarding materials accurate

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/domain/**/*.rs : In Rust domain layer, entity definitions and repository abstractions should be organized in the `entity/` module mirroring the gRPC schema, with repository interfaces using `async_trait`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/proto/**/*.proto : Keep gRPC contract definitions in `proto/stationapi.proto` and use `build.rs` with `tonic-build` to generate server code and `FILE_DESCRIPTOR_SET`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/presentation/controller/**/*.rs : gRPC presentation layer controller should wire service implementations (e.g., `MyApi`) to generated server types in `presentation/controller/grpc.rs`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/infrastructure/**/*.rs : Repository implementations in infrastructure layer should share an `Arc<PgPool>` connection pool

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/**/*.rs : Run `cargo test --lib --package stationapi` or `make test-unit` for unit tests focusing on entities and repository mocks without database

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/use_case/**/*.rs : Application logic in use case layer should implement contract traits defined in `traits/` module (e.g., `QueryUseCase` in `interactor/query.rs`)

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: When running locally, `cargo run -p stationapi` should rebuild schema from `data/create_table.sql`, import all `data/*.csv` files, and then boot the gRPC server

Applied to files:

• docs/architecture.md

🔇 Additional comments (1)

docs/architecture.md (1)

1-435: 包括的で高品質なアーキテクチャドキュメントの完成 — MD040対応確認済み

新しい docs/architecture.md は、StationAPI の4層アーキテクチャを明確に説明する優れたドキュメントです。以下の観点で評価します：

✅ 改善点:

• すべてのコードブロック（行39, 251, 332, 377, 391など）に言語指定（txt, rust, sql, protobuf）を正しく付与しており、Markdownlint MD040に完全対応しています
• Domain、UseCase、Infrastructure、Presentation の各層の責務が明確に定義され、依存性の方向（Domain 層に向かう）が正しく説明されています
• Row 構造体と Entity の区別（命名規則セクション）は、初心者開発者にとって非常に有用な説明になっています
• キャッシュ戦略セクションで N+1問題の回避方法（update_station_vec_with_attributes 関数）が具体的なコード例とともに説明されており、実装の根拠が明確です
• ディレクトリ構造が図解され、ファイルごとの責務が記載されているため、新規開発者のオンボーディング時に即座に参照できます

🔍 関連する learnings との整合性確認:

• Domain 層の entity/ モジュール構成と repository インターフェース（async_trait）が learnings と一致しています
• gRPC の tonic-build と stationapi.proto の位置付けが正確です
• Infrastructure 層の Arc パターンと Repository 実装が説明通りです
• Use Case 層の QueryInteractor と contract traits の関係が正確に記載されています

このドキュメントにより、#1350 で要求されたアーキテクチャドキュメント不足の問題が適切に解決されています。

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a76b3a7 and 61f091e.

📒 Files selected for processing (3)

• README.md
• docs/architecture.md
• docs/technical_debt.md

🧰 Additional context used

📓 Path-based instructions (1)

{docs/**/*.md,README.md}

📄 CodeRabbit inference engine (AGENTS.md)

For database, gRPC, or schema updates, add architectural notes under docs/ and synchronize README references to keep onboarding materials accurate

Files:

• docs/technical_debt.md
• docs/architecture.md
• README.md

🧠 Learnings (11)

📓 Common learnings

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to {docs/**/*.md,README.md} : For database, gRPC, or schema updates, add architectural notes under `docs/` and synchronize README references to keep onboarding materials accurate

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to {docs/**/*.md,README.md} : For database, gRPC, or schema updates, add architectural notes under `docs/` and synchronize README references to keep onboarding materials accurate

Applied to files:

• docs/technical_debt.md
• docs/architecture.md
• README.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/**/*.rs : Run `cargo test --lib --package stationapi` or `make test-unit` for unit tests focusing on entities and repository mocks without database

Applied to files:

• docs/technical_debt.md
• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/domain/**/*.rs : In Rust domain layer, entity definitions and repository abstractions should be organized in the `entity/` module mirroring the gRPC schema, with repository interfaces using `async_trait`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/proto/**/*.proto : Keep gRPC contract definitions in `proto/stationapi.proto` and use `build.rs` with `tonic-build` to generate server code and `FILE_DESCRIPTOR_SET`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/presentation/controller/**/*.rs : gRPC presentation layer controller should wire service implementations (e.g., `MyApi`) to generated server types in `presentation/controller/grpc.rs`

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/infrastructure/**/*.rs : Repository implementations in infrastructure layer should share an `Arc<PgPool>` connection pool

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to stationapi/src/use_case/**/*.rs : Application logic in use case layer should implement contract traits defined in `traits/` module (e.g., `QueryUseCase` in `interactor/query.rs`)

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: When running locally, `cargo run -p stationapi` should rebuild schema from `data/create_table.sql`, import all `data/*.csv` files, and then boot the gRPC server

Applied to files:

• docs/architecture.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to AGENTS.md : Keep `AGENTS.md` aligned with repository workflows and update it in the same pull request when workflows, environment requirements, or endpoints change

Applied to files:

• README.md

📚 Learning: 2025-11-25T10:50:36.694Z

Learnt from: CR
Repo: TrainLCD/StationAPI PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T10:50:36.694Z
Learning: Applies to AGENTS.md : Introducing new tables, endpoints, or feature flags must come with matching updates to `AGENTS.md` and any other affected guidance documents

Applied to files:

• README.md

🪛 markdownlint-cli2 (0.18.1)

docs/architecture.md

39-39: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

251-251: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

332-332: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

377-377: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

---

391-391: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (12)

README.md (1)

15-17: ✅ ドキュメント参照の追加は適切です。

新規アーキテクチャドキュメントへのリンク追加は、既存ドキュメント参照と同じスタイルで統一されており、ユーザーの発見性が向上します。相対パス docs/architecture.md も正確です。

docs/technical_debt.md (3)

212-224: ✅ アーキテクチャ完了状況の記録は正確です。

技術負債の「アーキテクチャドキュメント不足」をステータステーブルで対応済みとして記録し、対応領域（4層構造、命名規則、キャッシュ戦略、データフロー）を明確に列挙しています。学習の要件「architectural notes under docs/」を満たしています。

---

227-229: SQL設計ドキュメント化は今後の課題として明確に整理されています。

「複雑なクエリの使用意図がインラインコメントに留まる」という残存課題を分離し、優先度テーブル（行323）で「低優先度」に位置づけることで、段階的な改善が期待できます。

---

319-319: 優先度テーブルとステータスセクションが整合していることを確認しました。

行212-224で対応済みとしたアーキテクチャドキュメント項目が、行319で「高」（取消線）として反映されており、矛盾がありません。

docs/architecture.md (8)

61-126: 4層構造の説明は明確で実装に基づいています。

Domain層（Entity、Repository Interface）→ UseCase層（Interactor、DTO）→ Infrastructure層（Repository実装、Row構造体）→ Presentation層（gRPC Controller）という依存方向が正確に説明されており、学習要件を満たしています。各層の責務表（行65-86）により、ファイル構成との対応が一目瞭然です。

---

128-167: データベース設計説明が包括的です。

テーブル構成、PostgreSQL拡張（pg_trgm, btree_gist）、インデックス例、スキーマ更新時の手順チェックリスト（マイグレーション→Row→Entity→変換→DTO）など、実装者が実際に従う流れが文書化されています。

---

169-196: gRPC/Proto更新ガイドラインが実用的です。

14のエンドポイント一覧表、後方互換性のための optional キーワード使用例、DTO更新・テスト更新への注記により、新フィールド追加時の手順が明確化されています。

---

199-264: 命名規則の Row vs Entity 区別が鮮明です。

Infrastructure層の StationRow（DBカラム名と一致、snake_case、ロジック不在）と Domain層の Station（ビジネスセマンティクス、ネスト構造、多言語対応）の違いを表で示し、変換フロー図（252-263行）で一連のプロセスを可視化しています。これは issue #1350 で要求された「命名規則（Row構造体と Entity の区別）」を満たしています。

---

267-326: キャッシュ戦略の設計判断が明確に文書化されています。

• バッチクエリによる暗黙的キャッシュ: query.rs:169-265の update_station_vec_with_attributes を参照し、N+1問題回避のコード例を示す
• HashSet による重複排除: query.rs:223での実装例を引用
• キャッシュなし設計の理由: データ規模（約9,000駅）、更新頻度、ステートレス設計
• 将来の検討事項: moka/lruクレート、タグベース無効化

issue #1350で要求された「キャッシュ戦略の判断理由（query.rs付近参照）」を具体的にかつ正当に説明しており、要件を満たしています。

---

328-386: データフロー説明は段階的かつ完全です。

典型的なリクエストフロー（Client → Presentation → UseCase → Infrastructure → Domain → 逆方向変換 → gRPC Response）をASCII図で可視化し、エラー伝播チェーン（DomainError → UseCaseError → PresentationalError → tonic::Status）を明示しています。新規開発者のオンボーディングに有用です。

---

389-435: ディレクトリ構造表記は実装と整合しています。

stationapi/src/ 配下の domain/, use_case/, infrastructure/, presentation/ 各層が、実際のファイル配置（entity/, interactor/, dto/, controller/ など）とともに説明されており、PR objectives で参照されている query.rs:169-265 も行番号精度で記載されています。

---

439-442: 関連ドキュメントリンクが正確です。

• [技術負債分析レポート](./technical_debt.md)
• [リポジトリテストガイド](./repository_testing.md)
• [データ貢献ガイドライン](../data/README.md)

相対パスで docs/ ディレクトリ内からの参照、および親ディレクトリ data/ への参照が正確に設定されており、リンク切れのリスクがありません。