server-actions-vs-api-optimizer

# Server Actions vs API Routes Optimizer

Analyze existing routes and recommend whether to use Server Actions or traditional API routes based on specific use case patterns, including authentication flows, data revalidation, external API calls, and client requirements.

## Core Capabilities

### 1. Analyze Existing Routes

To analyze current route architecture:

- Scan app directory for route handlers and Server Actions
- Identify patterns in request/response handling
- Detect authentication, revalidation, and external API usage
- Use `scripts/analyze_routes.py` for automated analysis

### 2. Provide Recommendations

Based on analysis, provide recommendations using the decision matrix from `references/decision_matrix.md`:

- **Server Actions**: Form submissions, mutations with revalidation, simple data updates
- **API Routes**: External API proxying, webhooks, third-party integrations, non-form mutations
- **Hybrid Approach**: Complex flows requiring both patterns

### 3. Generate Migration Plans

When refactoring is recommended:

- Identify specific routes to convert
- Provide step-by-step migration instructions
- Show before/after code examples
- Highlight breaking changes and client updates needed

## When to Use Server Actions

Prefer Server Actions for:

1. **Form Submissions**: Direct form action handling with progressive enhancement
2. **Data Mutations with Revalidation**: Operations that need `revalidatePath()` or `revalidateTag()`
3. **Simple CRUD Operations**: Direct database mutations from components
4. **Authentication in RSC**: Auth checks in Server Components
5. **File Uploads**: Handling FormData directly
6. **Optimistic Updates**: Client-side optimistic UI with server validation

**Benefits**:
- Automatic POST request handling
- Built-in CSRF protection
- Type-safe with TypeScript
- Progressive enhancement (works without JS)
- Direct access to server-side resources
- Simpler code for common patterns

## When to Use API Routes

Prefer API routes for: