SasaTech Architecture

アーキテクチャ概要

Feature-based Layer Architecture for Next.js (App Router + Supabase)

レイヤー構成

Handler リクエスト/レスポンス、バリデーション、認証 ↓ Service ビジネスロジック、複数 Repository 連携 ↓ Repository データアクセス Adapter 外部 API 連携（Stripe, Resend 等）

ディレクトリ構成

src/ ├── app/ # Next.js App Router │ ├── (auth)/ # 認証が必要なルートグループ │ ├── (public)/ # 公開ルートグループ │ └── api/ # API Routes (薄いエントリーポイント) │ ├── features/ # 機能単位のモジュール │ └── [feature]/ │ ├── index.ts # 公開API │ └── core/ │ ├── schema.ts # Zodスキーマ + 型定義 │ ├── handler.ts # リクエスト / レスポンス処理 (server-only) │ ├── service.ts # ビジネスロジック (server-only) │ ├── repository.ts # データアクセス (server-only) │ ├── adapter.ts # 外部API連携 (server-only) │ ├── fetcher.ts # API呼び出し │ └── hooks.ts # SWR Hook等 │ ├── components/ # 共通UIコンポーネント ├── hooks/ # 共通Hooks ├── lib/ # ユーティリティ │ └── adapters/ # 外部サービス連携 └── types/ # 共通型定義、Supabase生成型

ガイドとルールの違い

このスキルは ガイド と ルール の2種類のドキュメントで構成されています。

項目 ガイド ルール

目的 アーキテクチャや実装パターンの理解を深める 守るべき制約を明確に定義する

内容 HOW / WHY — 設計思想、セットアップ手順、コード例 DO / DON'T — NG例とOK例による判定基準

形式 チュートリアル形式 メタデータ（impact, tags）付きの短いルール形式

読むタイミング プロジェクト参加時の学習、設計判断の参考 コード実装時の準拠確認、コードレビュー

ガイド

ガイド 説明

architecture.md Feature-based Layer Architecture の全体設計。レイヤー構成、責務分離、ディレクトリ構成

architecture/handler.md Handler層の実装。リクエスト処理、バリデーション、認証チェック、エラーハンドリング

architecture/service.md Service層の実装。ビジネスロジック、Repository/Adapter連携、トランザクション管理

architecture/repository.md Repository層の実装。データアクセスの抽象化、Supabaseクエリのカプセル化

architecture/adapter.md Adapter層の実装。外部サービス（決済、メール、AI等）との連携をカプセル化

testing.md レイヤーごとのテスト戦略。Unit / Integration テストの範囲とモック方針

database.md データベース設計。コメント規約、マイグレーション、Supabase との連携

logging.md pino を使用した構造化ログの実装。レイヤーごとのログ出力方針

setup.md 新規プロジェクトのセットアップ手順。依存パッケージ、基盤ファイルの配置

ルール

カテゴリ

カテゴリ Prefix

アーキテクチャ arch-

データ data-

サーバーサイド保護 server-

スキーマ・型定義 schema-

レスポンス response-

テスト test-

バリデーション validation-

命名規則 naming-

フロントエンド frontend-

インパクト

Impact は、違反時にアーキテクチャへ与える影響の深刻度で定義します。

Impact 基準

CRITICAL アーキテクチャの根幹が壊れる。違反するとこの設計パターン自体が成立しない

HIGH アーキテクチャの整合性や保守性を大きく損なう

MEDIUM コードの品質や一貫性を低下させる

LOW 開発体験やパターンの統一に関する推奨事項

アーキテクチャ (arch- )

ルール Impact 説明

arch-three-layers CRITICAL Handler → Service → Repository, Adapter の構成を必ず経由

arch-feature-structure CRITICAL 機能単位で features/ にモジュール化

arch-external-services HIGH Stripe, Resend 等の外部サービスは Adapter 経由

arch-logging-strategy MEDIUM pino で構造化ログ、console.log 禁止

データ (data- )

ルール Impact 説明

data-no-getall HIGH 全件取得禁止、MAX_LIMIT でサーバー側上限を強制

data-pagination HIGH リスト取得は必ずページネーション付きで総件数を返却

data-comment-required LOW テーブル・カラムに日本語コメント必須

サーバーサイド保護 (server- )

ルール Impact 説明

server-supabase-via-api CRITICAL クライアントから Supabase 直接使用禁止、API Route 経由必須

server-only-directive HIGH Service/Repository に import 'server-only' を必須で記述

server-no-public-env HIGH 機密情報（Supabase, API キー）に NEXT_PUBLIC_ 禁止

スキーマ・型定義 (schema- )

ルール Impact 説明

schema-single-source HIGH 型定義は schema.ts に一元化、分散禁止

schema-no-types-file MEDIUM Feature 内に types.ts 作成禁止

schema-zod-infer MEDIUM Input 型は手書きせず z.infer<typeof schema> で導出

レスポンス (response- )

ルール Impact 説明

response-apperror MEDIUM エラーは AppError クラスでスロー、生の Error 禁止

response-helpers LOW ok() , created() , notFound() 等のヘルパーを使用

テスト (test- )

ルール Impact 説明

test-layer-mocking HIGH 各レイヤーは直下の依存のみをモック

test-server-only MEDIUM server-only はテスト環境でモック必須

test-file-location LOW テストファイルは tests に配置

test-naming LOW テストは日本語で意図を明確に

バリデーション (validation- )

ルール Impact 説明

validation-body MEDIUM POST/PATCH のリクエストボディは Zod でバリデーション

validation-params MEDIUM URL パラメータ（ID 等）も Zod でバリデーション

命名規則 (naming- )

ルール Impact 説明

naming-files LOW ファイル・ディレクトリ名は kebab-case（フレームワーク規約ファイルを除く）

naming-methods LOW Repository: findMany /findById 、Service: get* /create*

フロントエンド (frontend- )

ルール Impact 説明

frontend-fetcher LOW Feature ごとに fetcher.ts を作成して API 呼び出しを集約

frontend-hooks LOW SWR を使用した Hook パターンでデータ取得