Effect Service Design

Effect Service Design

Treat a service as an authority seam: a cohesive capability whose requirements should propagate through Effect context. An Effect service module owns the service contract, construction, production Layer, and any honest reusable test implementation that belong to the same capability.

1. Establish the local rules

Read the nearest AGENTS.md, architecture docs, coding standards, project Effect guidance, pinned Effect version/source, and relevant vendored examples. Prefer current project-compatible patterns over remembered APIs.

Complete when: the governing files and pinned source examples have been read and recorded for use in later decisions.

2. Select the branch

• Design branch: for a new service or a focused redesign, bound the capability, trace one caller-visible operation to every effect, then continue below.
• Audit branch: for a codebase, package, feature slice, or diff, read and follow references/AUDIT.md, applying the rules below to every candidate it finds.

Complete when: one branch is selected, its scope is bounded, and the caller-visible operations in scope are named.

3. Apply the service test

A real service owns at least one meaningful capability:

• authority over persistence, credentials, external I/O, runtime resources, configuration, time, randomness, or lifecycle;
• cohesive effect sequencing or policy reused across entrypoints;
• state or behavior with real production and test/runtime variation;
• enough implementation complexity that deleting the module would spread complexity into callers.

Prefer an existing Effect service such as Clock, Crypto, Random, Config, HttpClient, FileSystem, or Path before defining an application service.

Keep these as values or pure modules:

• parsed domain inputs and per-call request data;
• deterministic calculations, projections, parsers, and constructors;
• options that select policy for one call;
• framework values confined to their adapter;
• wrappers that only rename or forward another service.

A test-only desire to inject a value is not enough. The seam must represent real ownership or variability in production.

Complete when: the deletion test and the existing-service/adapter audit both support either “service” or “value,” and the rejected alternative is stated plainly.

4. Place the authority seam

• Domain modules stay pure.
• Application services own operation policy and application-owned ports.
• A port's tag and interface live beside the application operation that needs them.
• A concrete adapter owns its technology-specific make and layer; it need not share a file with the application-owned port.
• Composition roots select and provide concrete Layers. They do not become reusable policy modules.
• Runtime bindings are yielded in the composition root or owning adapter, then hidden behind application/domain types.

Yield stable dependencies while building the Layer and close over them in service methods. Yield request-, fiber-, or operation-scoped context inside the method that uses it. Let requirements propagate until the module that truthfully chooses an implementation provides them.

Passing an external library's constructor options remains correct after the owning adapter has yielded the relevant runtime capability. React props, request values, domain inputs, and framework constructors are not Effect dependency injection.

Complete when: dependencies point inward, raw technology types stop at adapters, and no inner caller chooses a concrete implementation it does not own.