bunjs-architecture

What this skill does

# Bun.js Clean Architecture Patterns

## Overview

This skill covers layered architecture, clean code patterns, camelCase naming conventions, and structured implementation workflows for Bun.js TypeScript backend applications. Use this skill when building complex, maintainable applications that require strict separation of concerns.

**When to use this skill:**
- Implementing layered architecture (routes → controllers → services → repositories)
- Establishing coding conventions and naming standards
- Designing database schemas with Prisma
- Creating API endpoint specifications
- Planning implementation workflows

**See also:**
- **dev:bunjs** - Core Bun patterns, HTTP servers, basic database access
- **dev:bunjs-production** - Production deployment, Docker, AWS, Redis
- **dev:bunjs-apidog** - OpenAPI specifications and Apidog integration

## Clean Architecture Principles

### 1. Layered Architecture

**ALWAYS** separate concerns into distinct layers with single responsibilities:

```
┌─────────────────────────────────────┐
│         Routes Layer                │  ← Define API routes, attach middleware
│    (src/routes/)                    │     Map to controllers
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│       Controllers Layer             │  ← Handle HTTP requests/responses
│    (src/controllers/)               │     Call services, no business logic
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│        Services Layer               │  ← Implement business logic
│    (src/services/)                  │     Orchestrate repositories
└──────────────┬──────────────────────┘     No HTTP concerns
               │
┌──────────────▼──────────────────────┐
│      Repositories Layer             │  ← Encapsulate database access
│  (src/database/repositories/)       │     Use Prisma, type-safe queries
└─────────────────────────────────────┘     No business logic
```

**Critical Rules:**
- Controllers NEVER contain business logic (only HTTP handling)
- Services NEVER access HTTP context (no `req`, `res`, `Context`)
- Repositories are the ONLY layer that touches Prisma/database
- Each layer depends only on layers below it

### 2. Dependency Flow

```typescript
// ✅ CORRECT: Downward dependency flow
Routes → Controllers → Services → Repositories → Database

// ❌ WRONG: Upward dependency (service accessing controller)
Service imports from Controller  // NEVER DO THIS

// ❌ WRONG: Skip layers (controller accessing repository directly)
Controller → Repository  // Should go through Service
```

### 3. Separation of Concerns

| Layer | Responsibilities | Forbidden |
|-------|------------------|-----------|
| **Routes** | Define endpoints, attach middleware, map to controllers | Business logic, DB access |
| **Controllers** | Extract data from HTTP, call services, format responses | Business logic, DB access, validation logic |
| **Services** | Business logic, orchestrate operations, manage transactions | HTTP handling, direct DB access |
| **Repositories** | Database queries, type-safe Prisma operations | Business logic, HTTP handling |

## camelCase Conventions (CRITICAL)

### Why camelCase Everywhere?

**TypeScript-first full-stack development requires ONE naming convention across all layers:**
- ✅ Database → Prisma → TypeScript → API → Frontend (1:1 mapping)
- ✅ Zero translation layer = zero mapping bugs
- ✅ Autocomplete works perfectly everywhere
- ✅ Type safety maintained end-to-end

**This is non-negotiable for our stack.**

### API Field Naming: camelCase

**CRITICAL: All JSON REST API field names MUST use camelCase.**

**Why:**
- ✅ Native to JavaScript/JSON - No transformation needed
- ✅ Industry standard - Google, Microsoft, Facebook, AWS use camelCase
- ✅ TypeScript friendly - Direct mapping to interfaces
- ✅ OpenAPI/Swagger convention - Standard for API specs
- ✅ Auto-generated clients - Expected by code generation tools

**Examples:**
```typescript
// ✅ CORRECT: camelCase
{
  "userId": "123",
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "[email protected]",
  "createdAt": "2025-01-06T12:00:00Z",
  "isActive": true,
  "phoneNumber": "+1234567890"
}

// ❌ WRONG: snake_case
{
  "user_id": "123",
  "first_name": "John",
  "created_at": "2025-01-06T12:00:00Z"
}

// ❌ WRONG: PascalCase
{
  "UserId": "123",
  "FirstName": "John"
}
```

**Consistent Application:**

1. **Request Bodies**: All fields in camelCase
2. **Response Bodies**: All fields in camelCase
3. **Query Parameters**: Use camelCase (`pageSize`, `sortBy`, `orderBy`)
4. **Zod Schemas**: Define fields in camelCase
5. **TypeScript Interfaces**: Match API camelCase

### Database Naming: camelCase

**CRITICAL: All database identifiers (tables, columns, indexes, constraints) use camelCase.**

**Why:**
- ✅ Stack consistency - TypeScript is our primary language
- ✅ Zero translation layer - Database names map 1:1 with TypeScript types
- ✅ Reduced complexity - No snake_case ↔ camelCase conversion
- ✅ Modern ORM compatibility - Prisma, Drizzle, TypeORM work seamlessly
- ✅ Team productivity - Full-stack TypeScript developers think in camelCase

**Naming Rules:**

**1. Tables:** Singular, camelCase with `@@map()` to plural
```prisma
model User {
  userId String @id
  // ...
  @@map("users")  // Table name: users
}
```

**2. Columns:** camelCase
```prisma
userId, firstName, emailAddress, createdAt, isActive
```

**3. Primary Keys:** `{tableName}Id`
```prisma
userId    // in users table
orderId   // in orders table
productId // in products table
```

**4. Foreign Keys:** Same as referenced primary key
```prisma
model Order {
  orderId String @id
  userId  String  // references users.userId
  user    User    @relation(fields: [userId], references: [userId])
}
```

**5. Boolean Fields:** Prefix with is/has/can
```prisma
isActive, isDeleted, isPublic
hasPermission, hasAccess
canEdit, canDelete
```

**6. Timestamps:** Consistent suffixes
```prisma
createdAt      // creation time
updatedAt      // last modification
deletedAt      // soft delete time
lastLoginAt    // specific event times
publishedAt
verifiedAt
```

**7. Indexes:** `idx{TableName}{ColumnName}`
```prisma
@@index([emailAddress], name: "idxUsersEmailAddress")
@@index([userId, createdAt], name: "idxOrdersUserIdCreatedAt")
```

**8. Constraints:**
```prisma
// Foreign keys (Prisma auto-generates, but can specify)
@@index([userId], map: "fkOrdersUserId")

// Unique constraints
@@unique([emailAddress], name: "unqUsersEmailAddress")
```

### Prisma Schema Example (Perfect Mapping)

```prisma
model User {
  userId       String   @id @default(cuid())
  emailAddress String   @unique
  firstName    String?
  lastName     String?
  phoneNumber  String?
  isActive     Boolean  @default(true)
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
  lastLoginAt  DateTime?

  orders       Order[]
  sessions     Session[]

  @@index([emailAddress], name: "idxUsersEmailAddress")
  @@index([createdAt], name: "idxUsersCreatedAt")
  @@map("users")
}

model Order {
  orderId      String   @id @default(cuid())
  userId       String
  totalAmount  Decimal  @db.Decimal(10, 2)
  orderStatus  String
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt

  user         User     @relation(fields: [userId], references: [userId])
  orderItems   OrderItem[]

  @@index([userId], name: "idxOrdersUserId")
  @@index([createdAt], name: "idxOrdersCreatedAt")
  @@map("orders")
}

model OrderItem {
  orderItemId String   @id @default(cuid())
  orderId     String
  productId   String
  quantity    Int
  unitPrice   Decimal  @db.Decimal(10, 2)

  order       Order    @relation(fields: [orderId], references: [orderId])

  @@index([orderId], name: "idxOrderItemsOrderId")
  @@map("orderItems")
}
```

### TypeScript Types (Perfect Match)

```typescript
// Exact 1:1 mapping with database and API
interface User {
  userId: string;
  emailAddr