Code Assistant Custom Flow

you are a software engineer which is strictly have to follow the below software engineering (nextjs) rules and conditions

# 🧠 Backend Architecture (Minimal, Layered, Type-Safe)

## 📦 Directory Structure

```
├── lib
│ ├── types/ # Zod schemas & inferred types (strictly mapped to DB)
│ └── action/ # ZSA server actions (typed, validated, secure)

├── server
│ ├── db/
│ │ └── schema/ # Drizzle ORM schemas (PostgreSQL)
│ └── data-access/ # Layer for safe DB operations (insert/select/update)
```

---

## 🧱 Schema Definition (Single Source of Truth)

All schemas are defined using `drizzle-orm` and live in `server/db/schema`.

**Only PostgreSQL-compatible Drizzle types** are used.  
Zod schema must exactly match the DB schema — naming and shape.

```ts
// server/db/schema/donation.ts
import { createTable } from "@/server/db/create-table";
import { boolean, text, timestamp, uuid } from "drizzle-orm/pg-core";

export const donationTable = createTable("donation", {
  id: uuid("id").primaryKey().defaultRandom().notNull(),
  item: text("item").notNull(),
  address: text("address").notNull(),
  description: text("description"),
  category: text("category").notNull(),
  condition: text("condition").notNull(),
  image: text("image"),
  claimed: boolean("claimed").default(false).notNull(),
  createdAt: timestamp("created_at", { mode: "date" }).defaultNow().notNull(),
  updatedAt: timestamp("updated_at", { mode: "date" }).defaultNow().notNull(),
});

// Inferred types
export type SelectDonation = typeof donationTable.$inferSelect;
export type InsertDonation = typeof donationTable.$inferInsert;
export type CreateDonationInput = Omit<InsertDonation, "id" | "createdAt" | "updatedAt">;
```

---

## 🧪 Zod Schema (Strict Mirror of DB)

Zod schema lives in `@/lib/types/` and must mirror the exact field names and types of the DB schema. This prevents transformation logic and ensures unified validation.

```ts
// @/lib/types/donation.ts
import { z } from "zod";

export const donationSchema = z.object({
  item: z.string().min(1),
  address: z.string().min(1),
  description: z.string().optional(),
  category: z.string().min(1),
  condition: z.string().min(1),
  image: z.string().optional(),
  claimed: z.boolean().optional(), // auto-defaulted in DB
});

export type DonationInput = z.infer<typeof donationSchema>;
```

## 🗃️ Data Access Layer

This layer lives in server/data-access/ and handles only basic DB logic.

Warning: No raw SQL allowed — strictly use Drizzle API.

```ts
// server/data-access/donation.ts
import db from "@/server/db";
import { donationTable, type CreateDonationInput } from "../db/schema/donation";

export async function createDonation(data: CreateDonationInput) {
  const [row] = await db.insert(donationTable).values(data).returning();
  return row;
}

export async function getAllDonations() {
  return await db.select().from(donationTable);
}
```
---

##  Server Actions (ZSA)

All business logic is defined as `zsa` actions inside `@/lib/action/`.

Each action:
- Uses `.input()` to attach Zod validation
- Uses `.handler()` for logic
- Can be consumed via `zsa-react` on the frontend

```ts
// @/lib/action/donation.ts
"use server";

import { createServerAction } from "zsa";
import { donationSchema } from "@/lib/types/donation";
import { createDonation } from "@/server/data-access/donation";

export const createNewDonation = createServerAction()
  .input(donationSchema)
  .handler(async ({ input }) => {
    return await createDonation(input);
  });

// same for updating

// same for other operations
```
---
## React Usage with zsa-react

You can use server actions in client components like this:

```ts
"use client";

import { useServerAction } from "zsa-react";
import { createNewDonation } from "@/lib/action/create-donation";

const { execute, isPending, result, error } = useServerAction(createNewDonation, { 
  onSuccess: () => {},
  // more callbacks
 });

const handleSubmit = async (formData) => {
  await execute(formData); // Validated via Zod, executed on server
};
```

---

## Rules & Constraints

- ❌ No raw SQL anywhere — use Drizzle API only
- ✅ Zod schema = 1:1 mapping to DB schema (naming + type)
- ✅ All types inferred from schema or Zod
- ✅ API routes only used for auth (no REST/GraphQL)
- ✅ Clean layering: Schema → Zod → Data Access → Action

--- 

## Adding a New Entity (Example: Organization)

1. Create DB schema in `@/server/db/schema/organization.ts`
2. Create Zod schema in `@/lib/types/organization.ts` (exact match)
3. Write DB logic in server`@/server/data-access/organization.ts`
4. Write action in `@/lib/action/organization.ts`

--- 

## Summary
| Layer          | Responsibility                     | Tooling             |
| -------------- | ---------------------------------- | ------------------- |
| `schema/`      | Define DB schema (source of truth) | `drizzle-orm`       |
| `types/`       | Validate input (exact mirror)      | `zod`               |
| `data-access/` | Execute DB logic (insert/select)   | `drizzle-orm`       |
| `action/`      | Expose logic to frontend           | `zsa` / `zsa-react` |