Imported from yukazakiri/koakademy (.agents/skills/backend-architecture-guidelines/SKILL.md). Install upstream with npx skills add yukazakiri/koakademy --skill backend-architecture-guidelines. Copyright stays with the author.

Backend Architecture Guidelines - 7-Layer Laravel-Native

This skill provides architectural guidelines for Laravel applications following a 7-layer Laravel-native architecture.

Table of Contents

• How to Use This Skill
• Architecture Overview
• Dependency Rules
• Layer Responsibilities
• Static Analysis with Deptrac
• Anti-Patterns to Avoid
• Decision Framework
• Architecture Decision Checklist
• Reference Documentation

How to Use This Skill

Quick Reference - Phase 1: Architecture Planning

Architecture Decision Checklist:

• 要件から適切なレイヤーを決定 (Layer Responsibilities)
• 依存関係ルールを検証 (Dependency Rules)
• DTO設計（Laravel Data）を検討
• Repository の必要性を判断 (Decision Framework)
• Anti-patternsチェック (Anti-Patterns)
• Deptrac設定を計画

詳細な規約:

• .claude/rules/backend/ - レイヤー構造、DTO、テスト、コーディング規約の詳細

Architecture Overview

7層レイヤードアーキテクチャ（Laravel-native）

┌─────────────────────────────────────────────────────────────┐
│                   Presentation Layer                         │
│               (Controller, Middleware, Inertia)             │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Request Layer                            │
│                (FormRequest, Validation)                    │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     UseCase Layer                            │
│                  (Business Logic, DTO)                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     Service Layer                            │
│                 (Shared/Reusable Logic)                     │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Repository Layer                          │
│              (Data Access Abstraction)                      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Model Layer                             │
│                  (Eloquent Models)                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Resource Layer                            │
│               (JSON Response Transformation)                │
└─────────────────────────────────────────────────────────────┘

ディレクトリ構造 (app/ 配下にフラット配置)

app/
├── Http/
│   ├── Controllers/
│   │   ├── Api/              # API Controllers（REST API）
│   │   └── Web/              # Web Controllers（Inertia.js用）
│   ├── Requests/             # FormRequests（バリデーション）
│   └── Resources/            # API Resources（JSONレスポンス）
├── UseCases/                 # UseCases（ビジネスロジック）
│   └── {Resource}/
│       ├── Create{Resource}UseCase.php
│       └── Update{Resource}UseCase.php
├── Services/                 # Services（共通ロジック）
├── Repositories/             # Repositories（データアクセス）
│   └── {Resource}/
│       ├── {Resource}RepositoryInterface.php
│       └── {Resource}Repository.php
├── Data/                     # DTOs（Laravel Data）
│   └── {Resource}/
│       ├── Create{Resource}Data.php
│       └── Update{Resource}Data.php
├── Models/                   # Eloquent Models
├── Policies/                 # Policies（認可）
└── Enums/                    # Enums（列挙型）

Dependency Rules

基本ルール

依存は上位層から下位層への一方向のみ

Presentation → Request → UseCase → Service/Repository → Model → Resource

各レイヤーの依存関係

Layer Responsibilities

各層の責務一覧

Web Controllers vs API Controllers

📖 詳細: .claude/rules/backend/02-layers.md

Static Analysis with Deptrac

Deptrac を使用してアーキテクチャ境界を静的解析で検証する。

# deptrac/layer.yaml
deptrac:
  paths:
    - ./app
  layers:
    - name: Presentation
      collectors:
        - type: directory
          value: app/Http/Controllers
    - name: Request
      collectors:
        - type: directory
          value: app/Http/Requests
    - name: UseCase
      collectors:
        - type: directory
          value: app/UseCases
    - name: Service
      collectors:
        - type: directory
          value: app/Services
    - name: Repository
      collectors:
        - type: directory
          value: app/Repositories
    - name: Model
      collectors:
        - type: directory
          value: app/Models
    - name: Resource
      collectors:
        - type: directory
          value: app/Http/Resources

  ruleset:
    Presentation:
      - Request
      - UseCase
      - Resource
    Request:
      - Data
    UseCase:
      - Repository
      - Service
      - Policy
    Service:
      - Repository
      - Model
    Repository:
      - Model
    Resource:
      - Model
    Model: []

# 検証コマンド
./vendor/bin/deptrac analyse --config-file=deptrac/layer.yaml

Anti-Patterns to Avoid

1. Controller でのビジネスロジック

// ❌ WRONG
class PostController extends Controller
{
    public function store(Request $request)
    {
        // ビジネスロジックがControllerに
        if (Post::where('user_id', auth()->id())->count() > 10) {
            throw new \Exception('Limit exceeded');
        }
        $post = Post::create($request->all());
        return response()->json($post);
    }
}

// ✅ CORRECT
class PostController extends Controller
{
    public function store(StorePostRequest $request, CreatePostUseCase $useCase)
    {
        $data = $request->getCreatePostData();
        $post = $useCase->execute($data);
        return response()->json(new PostResource($post), 201);
    }
}

2. UseCase での HTTP 依存

// ❌ WRONG
class CreatePostUseCase
{
    public function execute(Request $request): Post  // HTTP依存
    {
        return Post::create($request->all());
    }
}

// ✅ CORRECT
class CreatePostUseCase
{
    public function execute(CreatePostData $data): Post  // DTOを使用
    {
        return $this->repository->create(...);
    }
}

3. Web Controller での動的データ提供

// ❌ WRONG
class PostPageController extends Controller
{
    public function index()
    {
        return Inertia::render('Post/Index', [
            'posts' => Post::all(),  // 動的データをWeb Controllerで
        ]);
    }
}

// ✅ CORRECT
class PostPageController extends Controller
{
    public function index()
    {
        return Inertia::render('Post/Index', [
            'statusOptions' => PostStatus::toSelectArray(),  // 静的データのみ
        ]);
        // 動的データはReact側からAPI経由で取得
    }
}

Decision Framework

Repository を作成すべきケース

Repository を作成しなくても良いケース

📖 詳細: .claude/rules/backend/02-layers.md

Service を作成すべきケース

Architecture Decision Checklist

レイヤー配置

• コードは正しいレイヤーに配置されているか？
• 依存方向は上位→下位の一方向か？
• ビジネスロジックは UseCase に集約されているか？

Controller 設計

• Controller は HTTP handling のみか？
• UseCase を呼び出しているか？
• Web Controller は静的データのみ提供しているか？

UseCase 設計

• Input DTO (Laravel Data) を使用しているか？
• Repository Interface 経由でアクセスしているか？
• HTTP 依存がないか？

Repository 設計

• Interface と Implementation が分離されているか？
• トランザクション制御が適切か？
• Eloquent Model を返しているか？

DTO 設計

• #[TypeScript()] attribute が付与されているか？
• readonly property を使用しているか？
• FormRequest に DTO 変換メソッドがあるか？

Reference Documentation

詳細な実装ガイドと例:

• .claude/rules/backend/01-overview.md - アーキテクチャ全体像
• .claude/rules/backend/02-layers.md - 各レイヤーの詳細責務とコード例
• .claude/rules/backend/03-dto-data.md - Laravel Data による DTO 実装
• .claude/rules/backend/04-typescript-generation.md - TypeScript 型生成
• .claude/rules/backend/05-inertia-backend.md - Inertia.js バックエンド実装
• .claude/rules/backend/06-testing.md - テスト戦略
• .claude/rules/backend/07-best-practices.md - ベストプラクティス
• .claude/rules/backend/08-coding-standards.md - コーディング規約