# Backend

> Creating backend code (Next.js)

- Skill: `nocode-tegethoff/backend` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add nocode-tegethoff/backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nocode-tegethoff/backend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: nocode-tegethoff (https://skillmd.com/u/nocode-tegethoff)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nocode-tegethoff/backend

---

When implementing backend logic (server components, Server Actions, and route handlers):

- Prefer **server components and a data access layer (DAL)** for reads.
- Use **Server Actions** for UI-driven mutations, and **route handlers** for public/external APIs.
- Always **validate input with Zod** before any database or external calls.
- Keep all **auth, authorization, and business context** checks on the server.

## Architecture & layering

- Organize backend code into clear layers:
  - **Route handler / Server Action**: I/O, parsing, validation, HTTP concerns only.
  - **Service layer**: business rules, orchestration.
  - **Repository / DAL**: database access, Supabase queries, and caching.
- Keep each function **small and focused**, returning plain data objects (no JSX).
- Never access the database directly from client components.

## Server Actions vs. route handlers (high level)

- Use **Server Actions** when:
  - The only consumer is the **Next.js UI**.
  - You need **mutations + revalidation** (`revalidatePath`, `revalidateTag`).
  - You want built-in CSRF protection and form integration.
- Use **route handlers** (`app/api/.../route.ts`) when:
  - The API must be consumed by **other services or clients**.
  - You need **pure HTTP semantics** (RESTful endpoints, status codes, headers).

## Input validation & types

- Define Zod schemas for:
  - Request body
  - Query/search params
  - URL params (ids, cursors, etc.)
- Always:
  - Parse and validate before calling services/DAL.
  - Return `400` on validation failure with a safe, minimal error payload.
- Infer and export **TypeScript types** from schemas for end-to-end type safety.

## Data access & performance

- Centralize Supabase/DB access in the **DAL/repository** layer.
- Follow query rules:
  - Avoid N+1: use relations and well-designed queries.
  - Always paginate lists with stable ordering.
  - Select only the columns you actually need.
- Use **caching** where appropriate (React `cache`, Next data cache, tags) to reduce repeated queries.

## Security & robustness

- Derive `userId` / `businessId` from the **authenticated Supabase session**, never from client input.
- Enforce **authorization** at the service/DAL layer for every resource access.
- Handle errors explicitly:
  - Map expected errors to appropriate HTTP statuses.
  - Log unexpected errors server-side; never leak stack traces to clients.
- Be careful with secrets:
  - Keep secrets only in **server-side code** and environment variables.
  - Never expose service role keys to the client.

## Logging, observability & maintainability

- Log:
  - Key lifecycle events (created/updated/deleted entities).
  - Integration failures (Supabase, third-party APIs).
  - Security-relevant events (auth failures, permission denials).
- Keep logs structured and redact sensitive fields.
- Prefer **pure, testable functions** in services/DAL with explicit dependencies.
- Delete dead code and keep backend modules small, cohesive, and well-named.