# Traditional Flask API endpoint
@app.route('/api/project', methods=['POST'])
@jwt_required()
def create_project():
    data = request.get_json()
    # ... validate data with Pydantic ...
    user_id = get_jwt_identity()
    # ... database operations ...
    return jsonify({"message": "Project created"}), 201

// Traditional client-side fetch
const handleSubmit = async (data) => {
  const response = await fetch('/api/project', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
    body: JSON.stringify(data),
  });
  // ... handle response and UI state ...
};

// src/actions/project.ts
"use server";

import { z } from "zod";
import { createSafeActionClient } from "next-safe-action";
import { db } from "@/db"; // Our Drizzle instance
import { auth } from "@/auth"; // Our Better Auth instance

// 1. Define Zod schema (our "Pydantic" / "DRF Serializer")
export const createProjectSchema = z.object({
  name: z.string().min(3, "Project name must be at least 3 characters"),
});

// 2. Create a "safe action" client
// We can inject context, like checking if user is authenticated
const action = createSafeActionClient({
  async middleware() {
    const session = await auth(); // Check authentication
    if (!session?.user?.id) {
      throw new Error("Unauthorized: Please log in first");
    }
    return { userId: session.user.id };
  },
});

// 3. Define our Action
export const createProject = action(
  createProjectSchema, // Pass schema for validation
  async ({ name }, { userId }) => { // Receive validated "name" and "userId" from middleware

    // 4. Execute business logic (Drizzle DB operations)
    try {
      const newProject = await db.insert(projectsTable).values({
        name,
        ownerId: userId,
      }).returning();

      return { success: true, project: newProject[0] };

    } catch (error) {
      console.error(error);
      return { serverError: "Failed to create project, please try again later." };
    }
  }
);

// src/components/create-project-form.tsx
"use client";

import { useAction } from "next-safe-action/hook";
import { createProject, createProjectSchema } from "@/actions/project";

export function CreateProjectForm() {
  // 5. Use useAction hook
  const { execute, result, validationErrors, serverError, status } =
    useAction(createProject);

  const onSubmit = (data: z.infer<typeof createProjectSchema>) => {
    execute(data); // Execute directly
  };

  // ... form (can use react-hook-form) ...

  {/* 6. Elegantly handle states */}
  {status === "executing" && <p>Creating...</p>}
  {serverError && <p className="text-red-500">{serverError}</p>}
  {validationErrors?.name && <p>{validationErrors.name[0]}</p>}
  {result?.data?.success && <p>Project "{result.data.project.name}" created successfully!</p>}
}

// src/actions/project.ts (continued)
"use server";

import { redirect } from "next/navigation"; // Import server-side redirect
import { revalidatePath } from "next/cache"; // Import cache refresh utility
// ... other imports ...

export const createProject = action(
  createProjectSchema,
  async ({ name }, { userId }) => {

    let newProjectId: string;

    try {
      const newProject = await db.insert(projectsTable).values({
        name,
        ownerId: userId,
      }).returning({ id: projectsTable.id });

      newProjectId = newProject[0].id;

    } catch (error) {
      return { serverError: "Failed to create project" };
    }

    // After successful creation

    // 1. [Important] Refresh cache
    // Tell Next.js that '/dashboard' page data is stale and needs re-fetch on next visit
    revalidatePath("/dashboard");

    // 2. [Important] Execute server-side redirect
    // This must be called outside the try...catch block because it throws a special exception
    redirect(`/project/${newProjectId}`);

    // Note: Code after redirect() won't execute
  }
);

src/actions/
├── auth.actions.ts       # Handle login, registration, logout (interact with Better Auth)
├── payment.actions.ts    # Handle Stripe payments, create checkout sessions
├── credits.actions.ts    # Handle user AI credits (credits) increment/decrement
├── project.actions.ts    # (like above example) Handle project C/U/D
├── user.actions.ts       # Handle user profile updates, API key generation
└── index.ts              # (Optional) Export all actions for easier management

// src/actions/payment.actions.ts
"use server";

import { z } from "zod";
import { createSafeActionClient } from "next-safe-action";
import { db } from "@/db";
import { auth } from "@/auth";
import { stripe } from "@/payment/stripe-server"; // Our Stripe server-side instance
import { usersTable } from "@/db/schema";
import { eq } from "drizzle-orm";
import { absoluteUrl } from "@/lib/utils";

// 1. Define Schema
const createCheckoutSchema = z.object({
  planId: z.string(), // e.g., "pro_plan_monthly"
});

// 2. Define Action (also requires authentication)
const action = createSafeActionClient({ /* ...auth middleware... */ });

export const createCheckoutSession = action(
  createCheckoutSchema,
  async ({ planId }, { userId }) => {

    // 3. Get user info from Drizzle (like Stripe Customer ID)
    const user = await db.query.usersTable.findFirst({
      where: eq(usersTable.id, userId),
    });

    if (!user) return { serverError: "User does not exist" };

    const stripeCustomerId = user.stripeCustomerId || await createStripeCustomer(user);

    const returnUrl = absoluteUrl("/dashboard/billing");

    // 4. Call Stripe API to create session
    try {
      const session = await stripe.checkout.sessions.create({
        payment_method_types: ["card"],
        mode: "subscription",
        customer: stripeCustomerId,
        line_items: [{ price: process.env[planId], quantity: 1 }],
        success_url: returnUrl,
        cancel_url: returnUrl,
      });

      if (!session.url) {
        return { serverError: "Unable to create payment session" };
      }

      // 5. Return Stripe Checkout URL
      // Client receives this URL and redirects to Stripe payment page
      return { success: true, url: session.url };

    } catch (error) {
      console.error(error);
      return { serverError: "Stripe communication failed" };
    }
  }
);