bunjs-architecture

The bunjs-architecture skill provides a comprehensive framework for building maintainable, scalable, and type-safe backend applications using Bun.js and TypeScript. It is designed for senior developers and teams who prioritize clean architecture patterns and strict separation of concerns to avoid technical debt in complex systems. By enforcing a rigid layered approach, the skill ensures that business logic remains decoupled from HTTP handling and database persistence, facilitating easier testing, refactoring, and long-term maintenance of your codebase.

• Implements a strict four-layer architecture: Routes (API/Middleware) → Controllers (Request/Response) → Services (Business Logic) → Repositories (Prisma Database Access).

• Enforces non-negotiable camelCase naming conventions across all layers, including JSON REST API fields, Zod schemas, TypeScript interfaces, and database identifiers (tables, columns, foreign keys).

• Provides architectural guidance on dependency flow, preventing upward dependencies (e.g., services accessing controllers) and promoting unidirectional, downward data flow.

• Includes best practices for Prisma schema modeling, such as singular model naming with @@map table mapping, consistent timestamp suffixes, and boolean field prefixes (is/has/can).

• Optimizes the full-stack development experience by ensuring 1:1 mapping between database schemas and frontend data structures, eliminating the need for tedious translation layers or mapping utility functions.

• Offers structured implementation workflows for defining API endpoint specifications and mapping them to internal logic layers.

• Use this skill when initiating new Bun.js projects or refactoring legacy modules to adopt clean code principles.

• Always keep the layers isolated: controllers should never contain business logic, and services must never directly touch HTTP contexts like request or response objects.

• Utilize this skill to standardize naming, ensuring end-to-end type safety and perfect IDE autocomplete support for your API contracts.

• Follow the defined dependency flow strictly; skip layers only if it does not violate the separation of concerns, though routing through a service layer is always preferred for orchestration.

• Refer to sibling skills such as dev:bunjs for basic server setup, dev:bunjs-production for deployment strategies, and dev:bunjs-apidog for OpenAPI/Swagger integration.