Skip to content
Potola Art Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Repository Structure

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

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

1. 基本構造

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/ はユーザー向けアプリケーションの正式実装を配置する。

frontend/web/

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

主な対象:

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

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

3. backend

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

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

主な対象:

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

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

4. design

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

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とする。

上位文書の例:

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で表示・ビルドするための設定を配置する。

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/ は複数の実装領域から共有するコードを配置する。

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

shared

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

例:

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

Was this page helpful?