Architecture Document Creation Guide

本ガイドは、システム全体の基本設計書である <root>/docs/architecture.md の記述内容とMarkdownテンプレートを定義するものです。

Section Guidelines

architecture.md はシステム全体のアーキテクチャ、構成図、コンポーネント定義、およびデータフローを明記するドキュメントです。以下の5つの必須セクションで構成します。

1. ディレクトリ構造

• プロジェクト全体のディレクトリ構成と、主要なディレクトリ・ファイルの役割をTree形式等で明記します。

2. システムアーキテクチャ

• システム全体の概要構造および全体構成図を記述します。
• 作図は原則として Mermaid 図 (mermaid) で作成してください。

3. ソフトウェアコンポーネント構成

• 各ソフトウェアコンポーネント（<root>/apps/[<group>/]<component>）の役割、技術スタック、責任範囲を記述します。

4. 依存・データフロー

• コンポーネント間の依存関係、通信プロトコル（REST, gRPC等）、データフローを記述します。

5. 関連

• 関連する上位設計書（concept.md, security.md, plan.md 等）や外部参照資料へのリンクをまとめます。
• 意思決定記録 (DR) へのリンク規則: 本基本設計の決定根拠となる意思決定記録（DR-XXX.md）が存在する場合、 該当する技術選定・アーキテクチャ記述の直後に ([DR-001](./decision-records/DR-001.md)) の形式でインライン記述 し、「関連」セクションにも相互リンクを記載します。

---

Template

以下は architecture.md を作成する際の標準Markdownテンプレートです。

---
name: architecture.md
description: <システム全体の基本設計およびコンポーネント構成の定義>
timestamp: YYYY-MM-DD
ai: ai-coauthored
---

# System Architecture

## ディレクトリ構造

```txt
<root>/
├── docs/       # 設計ドキュメント
├── apps/       # ソフトウェアコンポーネントの実装コード
├── tests/      # テストコード
├── scripts/    # 実行用エントリーポイント
└── tools/      # スクリプト補助ツール
```

## システムアーキテクチャ

```mermaid
graph TD
    Client["Client (WebUI)"] --> API["API Gateway"]
    API --> ServiceA["Service A"]
    API --> ServiceB["Service B"]
```

## ソフトウェアコンポーネント構成

| コンポーネント名 | パス | 役割 | 主要技術スタック |
| :--- | :--- | :--- | :--- |
| `webui` | `apps/frontend/webui` | Web フロントエンド | TypeScript, React |
| `auth-service` | `apps/backend/auth` | 認証基盤 API | Python, FastAPI |

## 依存・データフロー

-   `webui` ➔ `auth-service`: HTTPS / REST API による認証リクエスト
-   `auth-service` ➔ DB: PostgreSQL 接続によるユーザーデータ参照 ([DR-001](./decision-records/DR-001.md))

## 関連

-   [concept.md](./concept.md)
-   [security.md](./security.md)
-   [plan.md](./plan.md)
-   [DR-001](./decision-records/DR-001.md)