Domain-Driven Design, Part 3: Services, Events and Repositories

// WHAT: RankingService is a Domain Service
// WHY: Ranking logic involves multiple Issue entities.
//      It cannot live on a single Issue because one Issue
//      does not know about the others.
//      It cannot live on Project because Project should not
//      know the details of Lexorank calculation.
//      It belongs in a Domain Service.

class RankingService {
  initialRank(existingIssues: Issue[]): Rank {
    if (existingIssues.length === 0) return Rank.INITIAL
    return Rank.after(existingIssues.at(-1)!.rank)
  }

  rankBetween(above: Issue | null, below: Issue | null): Rank {
    if (!above && !below) return Rank.INITIAL
    if (!above) return Rank.before(below!.rank)
    if (!below) return Rank.after(above.rank)
    return Rank.between(above.rank, below.rank)
  }
}

// WHAT: ProjectAuthorizationService is a Domain Service
// WHY: Authorization logic reads from Project (to check membership + role)
//      but does not belong ON Project — it is a cross-cutting concern
//      that would bloat the Project entity if placed there.

class ProjectAuthorizationService {
  assertCanManageMembers(project: Project, userId: string): void {
    const member = project.getMember(userId)
    if (!member) throw new ForbiddenError("Not a project member")
    if (member.role.value === "member") {
      throw new ForbiddenError("Only admins and owners can manage members")
    }
  }
}

"Does this logic belong to one specific entity?"
  Yes → put it on the entity as a method
  No, it involves multiple entities → Domain Service
  No, it is infrastructure (email, file storage) → Infrastructure layer

// WHAT: IssueAssigned is a Domain Event
// WHY: It records the fact that an assignment happened.
//      Any part of the system that cares about assignments
//      can subscribe to this event — without AssignIssueUseCase
//      needing to know about them.

class IssueAssigned implements DomainEvent {
  readonly eventId    = UniqueId.generate()
  readonly eventType  = "ISSUE_ASSIGNED"   // past tense — it already happened
  readonly occurredAt = new Date().toISOString()

  constructor(readonly payload: {
    issueId:    string
    projectId:  string
    assigneeId: string
    assignedBy: string
    issueTitle: string
  }) {}
}

AssignIssueUseCase
  ├── assigns issue in the database
  ├── calls EmailService.send()
  ├── calls NotificationService.create()
  ├── calls AnalyticsService.track()
  └── calls ActivityLog.append()

PROBLEM: Adding Slack notifications means modifying AssignIssueUseCase.
Every new side effect = a change to the use case.

AssignIssueUseCase
  ├── assigns issue in the database
  └── publishes IssueAssigned ──► message queue

NotificationHandler (reacts to the event)
  ├── sends email
  ├── creates notification record
  └── tracks analytics

BENEFIT: Adding Slack notifications means adding a new handler.
AssignIssueUseCase never changes.

// WHAT: IIssueRepository is the Repository interface
// WHY: The domain layer defines what it needs (find, save, delete)
//      without knowing how it is implemented.
//      The Use Case depends on this interface — not on any database.

// Domain layer — pure interface, no database driver
interface IIssueRepository {
  findById(projectId: string, issueId: string): Promise<Issue | null>
  findByProject(projectId: string, filters: IssueFilters): Promise<Issue[]>
  save(issue: Issue): Promise<void>
  delete(projectId: string, issueId: string): Promise<void>
}

// Infrastructure layer — the concrete implementation
// WHY SEPARATE: The Use Case never imports this class directly.
//               It only knows the interface above.
//               Swapping one database for another = write a new class,
//               touch zero Use Cases.

class IssueRepository implements IIssueRepository {
  constructor(private readonly db: Database) {}

  async findById(projectId: string, issueId: string): Promise<Issue | null> {
    // All storage complexity lives here — hidden from the domain
    const rows = await this.db.query(
      "SELECT * FROM issues WHERE project_id = ? AND issue_id = ?",
      [projectId, issueId]
    )
    return rows.length ? IssueMapper.toDomain(rows) : null
  }
}