Agenda

The real problem: we have no architecture

Backend modules share no agreed structure. Business logic, persistence and orchestration blur together, and every feature solves it a different way — so there's no shape to learn, lean on, or enforce.

One template, every module

<bounded-context>/
  domain/          Entity, Validator,
                   errors, ports — pure,
                   zero infra imports
  infrastructure/  Repository (the ONLY
                   place Prisma lives),
                   Adapters
  application/     Service — orchestrates
                   use cases
  wiring.ts        Composition root — the
                   ONLY place `new` is called
  index.ts         Curated barrel — the
                   public contract

All the logic lives in the bounded context

Consumers (api, enrich, web, …) hold ZERO business logic. They may call ONLY the application layer.

• The barrel exposes application services (+ domain types). It does not expose repositories or let consumers reach in.
• Consumers become thin orchestration: validate request → call a service → return. No Prisma, no domain rules in api/enrich.

How two contexts talk

A bounded context talks to another by depending on its application service — injected through Deps. No reaching into a neighbor's domain or repository.

// ai-message/application/aiMessageService.ts
export type AiMessageServiceDeps = {
  repository: Pick<AiMessageRepository, 'store' | 'getAiMessageById' | 'getActiveByIds'>
  aiMessageToneRepository: Pick<AiMessageToneRepository, 'getAiMessageToneById'>
  promptMirrorService: Pick<PromptMirrorService, 'mirrorOnSave'>                       // ← another BC
  aiReferencesManager: Pick<AiReferencesManager, 'getValidatedReferencesForAiMessage'> // ← another BC
  aiEntityRichTextService: Pick<AiEntityRichTextService, 'extractNewReferences'>       // ← another BC
  triggerFillDescription: typeof triggerFillDescription
}

export class AiMessageService {
  constructor(private readonly deps: AiMessageServiceDeps) {}
  // …calls this.deps.promptMirrorService.mirrorOnSave(...) — never `new`, never a singleton import
}

Real example — descriptionFillService composes four sibling services (aiResearch, aiMessage, aiSnippet, messageTemplate) the same way. Cross-context calls are explicit, typed, and mockable — the dependency graph is visible in the Deps.

Temporal is just another use case

A Temporal workflow is an application use case expressed in Temporal. It reaches a bounded context's logic through activities — activities call the wired application services.

// enrich/src/activities/descriptionFillActivities.ts
import { descriptionFillService } from '@enginy/common'
import { sanitizeForDb } from '@enginy/common/utils'

export async function saveEntityDescription({
  entityType, entityId, clientId, description,
}: { entityType: AiEntityType; entityId: string; clientId: number; description: string }): Promise<void> {
  await descriptionFillService.fillDescription({
    entityType, entityId, clientId, description: sanitizeForDb(description),
  })
}

The workflow owns the orchestration; the business logic stays in the bounded context. Temporal is a delivery technology at the edge, like HTTP.

Tests with no database, no mocks of Prisma

Because every dependency is injected, each service ships a testStubs builder — vi.fn()s shaped exactly like its Deps.

// ai-snippet/application/aiSnippetService.testStubs.ts  (trimmed)
export function buildAiSnippetServiceStubs(): { stubs: AiSnippetServiceStubs; service: AiSnippetService } {
  const stubs = {
    repository: { store: vi.fn(), getAiSnippetById: vi.fn() /* … */ },
    promptMirrorService: { mirrorOnSave: vi.fn() },
    aiReferencesManager: { getValidatedReferencesForAiSnippet: vi.fn() },
    triggerFillDescription: vi.fn(),
  } as unknown as AiSnippetServiceStubs

  stubs.repository.store.mockResolvedValue(undefined)
  const service = new AiSnippetService(stubs as unknown as AiSnippetServiceDeps)
  return { stubs, service }
}

// aiSnippetService.test.ts
it('mirrors to Langfuse after storing', async () => {
  const { stubs, service } = buildAiSnippetServiceStubs()
  await service.create({ /* … */ })
  expect(stubs.repository.store).toHaveBeenCalledOnce()
  expect(stubs.promptMirrorService.mirrorOnSave).toHaveBeenCalledOnce()
})

• No vi.mock('@enginy/db') — there's nothing to mock.
• The stub surface is locked to the Deps type — change the deps and the test file fails to compile, not silently at runtime.

Where do we wire it all together?

No recommendation — let's weigh both and decide as a team.

// ai-message/wiring.ts
export const aiMessageService =
  new AiMessageService({
    repository: new AiMessageRepository(),
    promptMirrorService,   // sibling singleton
    aiReferencesManager,
    triggerFillDescription,
  })
// index.ts re-exports the SINGLETON.

"Which composition root do we want as the standard? Let's decide as a team."

Is the ceremony worth it?