---
title: Repository Structure
---

本ドキュメントは、Potola の正式実装におけるコード・設計資産・ドキュメントの配置ルールを定義する。

技術選定やシステム全体の設計は `01-architecture.md` を正本とし、本ドキュメントでは「正式採用したものをどこに置くか」に限定する。

## 1. 基本構造

```text
potola/
├─ frontend/
│  └─ web/
├─ backend/
│  └─ supabase/
│     ├─ migrations/
│     ├─ seed/
│     ├─ functions/
│     └─ config.toml
├─ design/
│  ├─ figma-links.md
│  ├─ screen-map.md
│  ├─ handoff/
│  └─ exports/
│     └─ images/
├─ docs/
├─ docs-site/
│  ├─ blume.config.ts
│  ├─ package.json
│  ├─ package-lock.json
│  └─ theme.css
├─ packages/
│  ├─ shared/
│  ├─ ui/
│  └─ config/
├─ scripts/
├─ sandbox/
├─ experiments/
├─ .env.example
├─ package.json
├─ package-lock.json
└─ README.md
```

`sandbox/` と `experiments/` の詳細な利用ルールは `03-poc-and-experiments.md` で定義する。

## 2. frontend

`frontend/` はユーザー向けアプリケーションの正式実装を配置する。

```text
frontend/web/
```

ここには正式採用した本番コードのみを配置する。

主な対象:

- UIコンポーネント
- ルーティング
- 状態管理
- フロントエンド側のドメインロジック
- バックエンドや外部サービスへのクライアント処理

具体的な内部構造は、実装時点のアーキテクチャと既存コードを優先する。

## 3. backend

`backend/` はバックエンドの正式実装とバックエンド設定を配置する。

```text
backend/supabase/
├─ migrations/
├─ seed/
├─ functions/
└─ config.toml
```

主な対象:

- DB schema / migration
- seed
- RLS
- Edge Functions
- バックエンド設定

ここにも正式採用したコードのみを配置する。

## 4. design

`design/` はコードではなく、UI/UXに関する設計資産を保存する。

```text
design/
├─ figma-links.md
├─ screen-map.md
├─ handoff/
└─ exports/
   └─ images/
```

主な対象:

- Figmaリンク
- UI仕様
- 画面マップ
- handoff資料
- スクリーンショット
- デザイン用画像

Figma等から生成された未検証コードを正式実装として直接 `frontend/` に配置しない。検証が必要な生成コードの扱いは `03-poc-and-experiments.md` に従う。

## 5. docs

`docs/` はPotolaの仕様・設計・運用文書を保存する。

`docs/` を正式ドキュメント本文の唯一の正本とする。ドキュメントサイト用に本文を別のディレクトリへ複製しない。

ドキュメントは責務ごとに分離し、同じルールを複数ファイルに重複して定義しない。

各Markdownファイルのページタイトルはfrontmatterの `title` で管理する。Blumeがページタイトルを表示するため、Markdown本文にページタイトルのH1を重複して記述しない。新しく作成する文書の本文では、最上位の見出しをH2とする。

上位文書の例:

```text
docs/
├─ index.md
├─ 00-potola-philosophy.md
├─ 01-architecture.md
├─ 02-repository-structure.md
├─ 03-poc-and-experiments.md
└─ 04-coding-rules.md
```

## 6. docs-site

`docs-site/` は、`docs/` の正式ドキュメントをBlumeで表示・ビルドするための設定を配置する。

```text
docs-site/
├─ .gitignore
├─ blume.config.ts
├─ package.json
├─ package-lock.json
└─ theme.css
```

Gitで管理する主な対象:

- Blume設定
- 表示テーマ
- 依存関係定義とlockfile

Gitで管理しない対象:

- `node_modules/`
- `.blume/`
- `dist/`

これらは依存関係のインストールまたはビルドによって再生成できるため、リポジトリへ含めない。

`docs-site/` に正式ドキュメント本文を置かない。Blumeは `docs/` を直接参照し、本文の二重管理を避ける。

## 7. packages

`packages/` は複数の実装領域から共有するコードを配置する。

```text
packages/
├─ shared/
├─ ui/
└─ config/
```

### shared

複数領域で共有する型、バリデーション、環境非依存ロジックなどを配置する。

例:

```text
packages/shared/
├─ types/
├─ validation/
└─ utils/
```

### ui

複数アプリケーションで共有する必要が生じたUIコンポーネントを配置する。

単一のフロントエンド内でしか使用しないUIは、原則として `frontend/web/` 内に置く。

### config

複数領域で共有する設定・定数などを配置する。

### packages に置く判断基準

原則として、次の条件を満たすものを候補とする。

- 複数領域から利用する
- 特定の実行環境に過度に依存しない
- 共通化することで責務が明確になる

将来使うかもしれないという理由だけで先行して共通化しない。

## 8. scripts

`scripts/` は開発・CI・運用を補助するスクリプトを配置する。

例:

- 型生成
- migration補助
- seed実行
- CI補助
- 開発環境のセットアップ

アプリケーション本体のビジネスロジックは配置しない。

## 9. 正式実装の配置ルール

### Rule 1: 正式なアプリケーションコード

正式採用したフロントエンド／バックエンドのコードは、それぞれ `frontend/`、`backend/` に配置する。

### Rule 2: 試作コードを混在させない

PoCや一時的な技術検証を、正式実装ディレクトリに混在させない。

### Rule 3: 共通化を先行しない

コードは、実際に複数領域で共有する必要が生じてから `packages/` への移動を検討する。

### Rule 4: 既存構造を優先する

AI・開発者ともに、新しいディレクトリを作成する前に既存の配置と責務を確認する。

### Rule 5: Architectureとの責務を分離する

技術スタック、システム境界、インフラ構成などは `01-architecture.md` に従う。本ドキュメントでは、それらを重複して定義しない。

## 10. AIコーディング時の判断

AIはファイルを追加・移動する前に、以下を確認する。

1. 正式実装か、PoC・実験か。
2. 正式実装なら `frontend/`、`backend/`、`packages/` 等のどの責務に属するか。
3. 既存の同種コードがどこに配置されているか。
4. 新しいトップレベルディレクトリが本当に必要か。

PoC・実験の場合は `03-poc-and-experiments.md` を参照する。

## 11. 要約

| ディレクトリ         | 役割                  |
| -------------- | ------------------- |
| `frontend/`    | 正式なユーザー向けアプリケーション   |
| `backend/`     | 正式なバックエンド           |
| `design/`      | UI/UX設計資産           |
| `docs/`        | 仕様・設計・運用文書の正本      |
| `docs-site/`   | 正式ドキュメントの表示・ビルド設定 |
| `packages/`    | 実際に共有される共通コード       |
| `scripts/`     | 開発・CI・運用補助          |
| `sandbox/`     | 本番昇格候補のPoC（詳細は03）   |
| `experiments/` | 昇格前提ではない技術検証（詳細は03） |

本ドキュメントの目的は、正式実装の配置を一貫させ、AIと開発者が「どこにコードを置くか」で迷わない状態を維持することである。

---

作成日　2026.09.09