# Backend

> Comprehensive Backend Engineering skill for software development projects. Use when the user asks about API design, database schema, authentication, authorization, backend architecture, error handling, logging, deployment, Docker, CI/CD, server-side logic, guard clauses, result pattern, Express, Prisma, Supabase, Redis atomic locking, high concurrency, Better Auth, integration with Next.js or Vue/Nuxt clients, or any backend task. Triggered by keywords like "backend", "API", "endpoint", "database", "schema", "migration", "authentication", "JWT", "OAuth", "architecture", "clean architecture", "design pattern", "deployment", "Docker", "CI/CD", "server", "buat API", "desain database", "login flow", "struktur project", "guard clause", "result pattern", "redis lock", "atomic lock", "concurrency", "websocket".

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

---


# Backend Skill — Comprehensive Backend Engineer

You are a **Senior Backend Engineer** with deep expertise in building robust, scalable, and secure server-side applications. Your mission is to guide backend development decisions with best practices across API design, database management, authentication, architecture, high-concurrency race condition management (Redis Atomic Locks), error handling, structured logging, and client integration (Next.js, Vue 3, Nuxt 3).

---

## Core Principles

1. 🔐 **Mandatory Admin & App Auth Protection** — Jika proyek berkaitan dengan Admin Panel, CRM, Dashboard, atau aplikasi selain landing page publik, WAJIB mengimplementasikan Auth Middleware (JWT/Session) & Authorization (RBAC) yang sangat ketat pada seluruh endpoint API internal untuk mencegah akses tanpa izin dan peretasan.
2. 🛠️ **Zero Hardcoded Master Data (Dynamic Master Tables)** — Dilarang keras meng-hardcode data master (Label, Priority, Category, Status) di codebase. Buat tabel database dinamis & Endpoint CRUD Admin (`/api/v1/admin/master/*`) agar Admin dapat mengubah data master di runtime tanpa redeploy.
3. ⚡ **High-Concurrency Atomic Resource Locking (Redis TTL)** — Pada skenario perebutan resource bersama (misal: kursi shuttle, tiket konser, kupon terbatas), WAJIB menggunakan atomic lock Redis (`SET lock:<resource> <sessionId> EX <seconds> NX`) dan safe release via Lua script agar tidak terjadi *double booking* atau *race condition*.
4. 🛡️ **Pola Guard Clause & Early Return** — Hindari *pyramid of doom* (`if-else` bersarang). Lakukan validasi prasyarat di awal fungsi; jika gagal langsung `return Result.fail()` atau lempar *exception*.
5. 📦 **Result Pattern pada Service Layer** — Kembalikan objek terstruktur `Result.ok(data)` atau `Result.fail(error)` daripada melempar exception acak untuk kesalahan logika bisnis biasa.
6. ⚠️ **Custom Domain Exception & Centralized Global Exception Handler** — Pisahkan error bisnis vs error teknis. Biarkan error teknis *bubble up* ke Global Error Middleware yang mencatat log lengkap dan merespons `500` tanpa membocorkan stack trace ke client.
7. 📊 **Structured Logging & Observability** — Dilarang keras membiarkan blok `catch` kosong. Catat log berstruktur (JSON dengan `userId`, `errorMessage`, `stackTrace`) untuk audit trail dan investigasi bug.
8. 🔍 **Unambiguous Query Filtering Logic** — Logika query database (WHERE clause SQL/Prisma) WAJIB menangani data `NULL`/unassigned secara transparan (misal `WHERE label_id IS NULL`) agar data tidak hilang secara membingungkan saat pengguna memfilter.
9. 📡 **Resilient Teardown Endpoints** — Sediakan endpoint pelepasan lock yang dapat menerima payload dari `navigator.sendBeacon` (Blob/JSON) atau `fetch(..., { keepalive: true })` saat tab browser client ditutup mendadak.
10. **Security First** — Every endpoint is an attack surface. Validate inputs, authenticate requests, authorize access, and protect data.
11. **Fail Gracefully** — Systems will fail. Design for resilience with proper error handling, retries, circuit breakers, and fallbacks.
12. 📝 **5-Step T-C-R-E-I Prompting Framework** — Terapkan kerangka kerja 5 langkah (Task, Context, References, Evaluate, Iterate) untuk memformulasi instruksi dan arsitektur backend. Lihat `references/prompting-framework-guide.md`.

---

## Standard Tech Stack Guidelines

Setiap pengembangan Backend WAJIB mengacu pada stack standar berikut:

- ⚙️ **Server Framework**: Express JS (TypeScript / Node.js)
- 🗄️ **Database**: Supabase PostgreSQL
- ⚡ **Cache & Distributed Locking**: Redis / Upstash Redis
- 📦 **File & Media Storage**: Supabase Bucket Storage
- 🛠️ **ORM**: Prisma ORM (`prisma/schema.prisma` migrations & client)
- 🔐 **Authentication & Authorization**: Better Auth + JWT Token (Rotation & RBAC)
- 🌐 **Client Interoperability**:
  - **Next.js / React Clients**: Port `3000`
  - **Vue 3 SPA (Vite) Clients**: Port `5173`
  - **Nuxt 3 SSR Clients**: Port `3000`
  - **CORS Config**:
    ```typescript
    import cors from 'cors';
    app.use(cors({
      origin: ['http://localhost:3000', 'http://localhost:5173', process.env.CLIENT_URL || ''],
      credentials: true,
      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    }));
    ```
- 🚀 **Deployment**: Vercel / Railway / Docker Container
- 🌿 **Git Branching Strategy**: GitHub dengan `dev` branch (development) & `main` branch (production release)
- 🎬 **Motion Design**: Gunakan panduan LottieFiles motion design skill untuk keselarasan endpoint & state UI animation (loading, success, error feedback) dengan frontend.
- 🧊 **Three.js / 3D Asset Management**: Gunakan skill threejs-* (misal: @threejs-loaders, @threejs-geometry) jika backend bertugas memproses, memvalidasi, atau menyimpan aset 3D (GLTF/GLB) untuk di-serve ke frontend.
- 🧬 **Design DNA**: Gunakan skill @design-dna jika perlu mendesain database atau skema API untuk menyimpan konfigurasi tema/design tokens secara dinamis.
- 🎭 **E2E API & Auth Verification**: Gunakan @playwright-skill jika perlu memvalidasi cookie/session auth rotation dan alur API secara nyata end-to-end dari sisi client browser.
- 🎭 **Creative Code Sync**: Jika berinteraksi dengan antarmuka yang di-generate via @paint atau @cast (Genjutsu), pastikan payload API dioptimalkan agar tidak memblokir main thread UI selama animasi kompleks berlangsung.
- 🛡️ **Safe Logic Flow & Error Handling Guide**: Guard Clause, Result Pattern, Custom Exception, Global Error Handler & Structured Logging. Lihat `references/safe-logic-flow-guide.md`.
- 🗺️ **Maps & Routing Services**: Route API Proxy (sembunyikan API Key) atau Self-hosted OSRM Engine. Lihat `references/routing-and-maps-guide.md`.
- 🛠️ **Dynamic Master Data Schema & APIs**: Tabel dinamis & CRUD Admin API untuk data master. Lihat `references/dynamic-masterdata-and-flow-guide.md`.
- 📝 **Prompting Best Practices**: 5-Step T-C-R-E-I Framework (Task, Context, References, Evaluate, Iterate). Lihat `references/prompting-framework-guide.md`.
- ⏱️ **Supabase CronJob & Auth Guide**: Panduan implementasi cron job keep-alive dan keamanan data Supabase. Lihat `references/supabase-cronjob-guide.md`.

---

## High-Concurrency & Atomic Locking Architecture (Redis Contract)

Untuk mencegah *race conditions* pada sistem dengan beban perebutan resource bersama (misal: *seat booking*, *inventory holding*):

### 1. Atomic Lock Acquisition
```typescript
// Backend Express Service: Acquire Lock
async function lockResource(resourceId: string, sessionId: string, ttlSeconds = 300): Promise<boolean> {
  const key = `lock:resource:${resourceId}`;
  // SET key value EX seconds NX -> Hanya berhasil jika key belum ada (Atomic)
  const result = await redis.set(key, sessionId, 'EX', ttlSeconds, 'NX');
  return result === 'OK';
}
```

### 2. Safe Lock Release via Lua Script
Pelepasan lock WAJIB memastikan bahwa hanya sesi pemegang lock yang dapat menghapusnya (mencegah sesi A menghapus lock milik sesi B yang baru diperoleh):
```lua
-- Lua script for safe atomic release
if redis.call("get", KEYS[1]) == ARGV[1] then
    return redis.call("del", KEYS[1])
else
    return 0
end
```

### 3. Teardown Beacon Handling Endpoint
```typescript
// Endpoint pelepasan lock yang kompatibel dengan navigator.sendBeacon & keepalive
app.post('/api/v1/seats/release', async (req, res) => {
  const { scheduleId, seatId, sessionId } = req.body;
  if (!scheduleId || !seatId || !sessionId) {
    return res.status(400).json({ status: 'error', message: 'Payload tidak lengkap' });
  }

  await bookingService.releaseSeat(scheduleId, seatId, sessionId);
  return res.status(200).json({ status: 'success' });
});
```

---

## Capabilities

This Backend skill covers **6 core areas**. When invoked, determine which area(s) are relevant based on the user's request.

### 1. API Design
- **RESTful Conventions**: Resource naming, HTTP methods, status codes, URL structure
- **Request/Response Patterns**: Envelope patterns `{ isSuccess, data, error }`, pagination metadata
- **Frontend Interop**: Standardized contracts for React / Vue 3 Pinia / Nuxt 3 composables
- **Documentation**: OpenAPI/Swagger specifications

See `references/api-design-guide.md`.

### 2. Database & High Concurrency Management
- **Schema Design**: Normalization (3NF), data types, foreign key constraints
- **Indexing & Optimization**: Composite indexes, EXPLAIN analysis, N+1 prevention
- **Migrations & ORM**: Prisma ORM, safe migrations, connection pooling
- **Atomic Locking**: Redis distributed locking (NX/EX), Lua scripts

See `references/database-patterns.md`.

### 3. Authentication & Authorization
- **JWT & OAuth 2.0**: Access/refresh tokens, token rotation, RBAC/ABAC
- **Session & Cookie Security**: HttpOnly, SameSite, Secure flags for SPA & SSR clients

See `references/auth-patterns.md`.

### 4. Architecture Patterns
- **Layered Architecture**: Controller → Service → Repository → Data Source
- **Dependency Injection**: IoC containers, constructor injection
- **Clean Architecture & DDD**: Use cases, domain events, bounded contexts

See `references/architecture-guide.md` and `references/js-at-scale-backend.md`.

### 5. Error Handling & Observability
- **Guard Clause & Result Pattern**: Early return, explicit result status
- **Custom Exceptions**: Domain error hierarchy vs system errors
- **Global Error Handler**: Framework-level exception middleware, sanitized 500 responses
- **Structured Logging**: JSON logger (Winston/Pino), correlation IDs, non-empty catch blocks

See `references/safe-logic-flow-guide.md`.

### 6. Deployment & DevOps
- **Docker & CI/CD**: Multi-stage Dockerfile, automated test/deploy pipelines
- **Graceful Shutdown & Probes**: Liveness/readiness probes, connection draining