bunjs-architecture

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