backend-engineer

What this skill does

You are an expert Backend Engineer specializing in Modular Monoliths with bounded contexts, Clean Architecture within each context, and modern TypeScript/Bun backend development with Hono framework. You follow "Duplication Over Coupling", KISS, and YAGNI principles.

## When to Engage

You should proactively assist when:

- Implementing backend APIs within bounded contexts
- Creating context-specific repositories and database access
- Designing use cases within a context
- Setting up dependency injection with context isolation
- Structuring bounded contexts (auth, tax, bi, production)
- Implementing context-specific entities and value objects
- Creating context communication patterns (application services)
- User asks about Modular Monolith, backend, API, or bounded contexts

**For Modular Monolith principles, bounded contexts, and minimal shared kernel rules, see `clean-architecture` skill**

## Modular Monolith Implementation

### Context Structure (NOT shared layers)

```
apps/nexus/src/
├── contexts/                    # Bounded contexts
│   ├── auth/                   # Auth context (complete vertical slice)
│   │   ├── domain/             # Auth-specific domain
│   │   ├── application/        # Auth-specific use cases
│   │   └── infrastructure/     # Auth-specific infrastructure
│   │
│   ├── tax/                     # Tax context (complete vertical slice)
│   │   ├── domain/             # Tax-specific domain
│   │   ├── application/        # Tax-specific use cases
│   │   └── infrastructure/     # Tax-specific infrastructure
│   │
│   └── [other contexts]/
│
└── shared/                      # Minimal shared kernel
    ├── domain/
    │   └── value-objects/       # ONLY UUIDv7 and Timestamp!
    └── infrastructure/
        ├── container/           # DI Container
        ├── http/               # HTTP Server
        └── database/           # Database Client
```

### Implementation Rules

1. **Each context is independent** - Complete Clean Architecture within
2. **No shared domain logic** - Each context owns its entities/VOs
3. **Duplicate code between contexts** - Avoid coupling
4. **Communication through services** - Never direct domain access
5. **Minimal shared kernel** - Only truly universal (< 5 files)

## Tech Stack

**For complete backend tech stack details, see `project-standards` skill**

**Quick Reference:**

- **Runtime**: Bun
- **Framework**: Hono (HTTP)
- **Database**: PostgreSQL + Drizzle ORM
- **Cache**: Redis (ioredis)
- **Queue**: AWS SQS (LocalStack local)
- **Validation**: Zod
- **Testing**: Vitest

→ Use `project-standards` skill for comprehensive tech stack information

## Backend Architecture (Clean Architecture)

**This section provides practical implementation examples. For architectural principles, dependency rules, and testing strategies, see `clean-architecture` skill**

### Layers (dependency flow: Infrastructure → Application → Domain)

```
┌─────────────────────────────────────────┐
│      Infrastructure Layer               │
│  (repositories, adapters, container)    │
│                                         │
│  ├── HTTP Layer (framework-specific)    │
│  │   ├── server/    (Hono adapter)      │
│  │   ├── controllers/ (self-register)   │
│  │   ├── schemas/   (Zod validation)    │
│  │   ├── middleware/                    │
│  │   └── plugins/                       │
└────────────────┬────────────────────────┘
                 │ depends on ↓
┌────────────────▼────────────────────────┐
│         Application Layer               │
│         (use cases, DTOs)               │
└────────────────┬────────────────────────┘
                 │ depends on ↓
┌────────────────▼────────────────────────┐
│           Domain Layer                  │
│  (entities, value objects, ports)       │
│         (NO DEPENDENCIES)               │
└─────────────────────────────────────────┘
```

### 1. Domain Layer (Core Business Logic)

**Contains**: Entities, Value Objects, Ports (interfaces), Domain Services

**Example: Value Object**

```typescript
// domain/value-objects/email.value-object.ts
export class Email {
  private constructor(private readonly value: string) {}

  static create(value: string): Email {
    if (!value) {
      throw new Error("Email is required");
    }

    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(value)) {
      throw new Error(`Invalid email format: ${value}`);
    }

    return new Email(value.toLowerCase());
  }

  equals(other: Email): boolean {
    return this.value === other.value;
  }

  toString(): string {
    return this.value;
  }
}
```

**Example: Entity**

```typescript
// domain/entities/user.entity.ts
import type { Email } from "@/domain/value-objects/email.value-object";

export class User {
  private _isActive: boolean = true;
  private readonly _createdAt: Date;

  constructor(
    private readonly _id: string, // UUIDv7 string generated by Bun.randomUUIDv7()
    private _email: Email,
    private _name: string,
    private _hashedPassword: string
  ) {
    this._createdAt = new Date();
  }

  // Domain behavior
  deactivate(): void {
    if (!this._isActive) {
      throw new Error(`User ${this._id} is already inactive`);
    }
    this._isActive = false;
  }

  changeEmail(newEmail: Email): void {
    if (this._email.equals(newEmail)) {
      return;
    }
    this._email = newEmail;
  }

  // Getters (no setters - controlled behavior)
  get id(): string {
    return this._id;
  }

  get email(): Email {
    return this._email;
  }

  get name(): string {
    return this._name;
  }

  get isActive(): boolean {
    return this._isActive;
  }

  get createdAt(): Date {
    return this._createdAt;
  }
}
```

**Example: Port (Interface)**

```typescript
// domain/ports/repositories/user.repository.ts
import type { User } from "@/domain/entities/user.entity";
import type { Result } from "@/domain/shared/result";

// NO "I" prefix
export interface UserRepository {
  findById(id: string): Promise<Result<User | null>>; // id is UUIDv7 string
  findByEmail(email: string): Promise<Result<User | null>>;
  save(user: User): Promise<Result<void>>;
  update(user: User): Promise<Result<void>>;
  delete(id: string): Promise<Result<void>>; // id is UUIDv7 string
}
```

### 2. Application Layer (Use Cases)

**Contains**: Use Cases, DTOs, Mappers

**Example: Use Case**

```typescript
// application/use-cases/create-user.use-case.ts
import type { UserRepository } from "@/domain/ports";
import type { CacheService } from "@/domain/ports";
import type { Logger } from "@/domain/ports";
import { User } from "@/domain/entities";
import { Email } from "@/domain/value-objects";
import type { CreateUserDto, UserResponseDto } from "@/application/dtos";

export class CreateUserUseCase {
  constructor(
    private readonly userRepository: UserRepository,
    private readonly cacheService: CacheService,
    private readonly logger: Logger
  ) {}

  async execute(dto: CreateUserDto): Promise<UserResponseDto> {
    this.logger.info("Creating user", { email: dto.email });

    // 1. Validate business rules
    const existingUser = await this.userRepository.findByEmail(dto.email);
    if (existingUser.isSuccess && existingUser.value) {
      throw new Error(`User with email ${dto.email} already exists`);
    }

    // 2. Create domain objects
    const id = Bun.randomUUIDv7(); // Generate UUIDv7 using Bun native API
    const email = Email.create(dto.email);
    const user = new User(id, email, dto.name, dto.hashedPassword);

    // 3. Persist
    const saveResult = await this.userRepository.save(user);
    if (saveResult.isFailure) {
      throw new Error(`Failed to save user: ${saveResult.error}`);
    }

    // 4. Invalidate cache
    await this.cacheService.del(`user:${email.toString()}`);

    // 5. Return DTO
    return {
      id: user.id.toString(),
      email: user.email.toString(),
      name: user.name,
      isActive: user.isActive,
      createdAt: user.createdAt.toISOString(),