For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Structure an Effect codebase by domain

A domain is an area of application work. A service is a named interface for that work. A Layer describes how to build a service and supply its dependencies.¶

Group files by domain: src/coding/edit.ts puts an edit operation with the coding work it belongs to. Keep one service and its Layer in each file. Capture dependencies when building the service, so callers need only that service.¶

An entrypoint is where the application starts. Its composition root chooses and supplies implementations. Keep platform adapters behind service interfaces. An adapter implements an interface for a platform or provider.¶

Justin Bennett asked about folders and service organization. Sam Goodwin’s answer:¶

src/{domain} instead of src/{mechanism}. E.g. src/coding/edit.ts instead of src/tools/edit.ts. “tools” is the mechanism, “coding” is the domain.¶

The shape in one tree

A small app can use this layout:¶

src/
├── files/
│   ├── file-inspector.ts    Service, dependency capture, Layer
│   ├── stats.ts             Schema and expected errors
│   └── inspect-machine.ts   Optional finite lifecycle
├── platform/
│   └── files-node.ts        Platform adapter Layer
└── main.ts                  Composition root and runtime entrypoint
test/
└── files/
    └── file-inspector.test.ts

Domain folders own behavior. platform supplies implementations. rat-stack separates these jobs into packages; a small app can keep them in one package.¶

The rules that hold it together

Capture dependencies when constructing a service

Keep the service interface and its Layer together. FileInspector captures FileSystem during construction. Its methods have no filesystem requirement.¶

export class FileInspector extends Context.Service<
  FileInspector,
  {
    readonly inspect: (
      path: string
    ) => Effect.Effect<FileStats, FileStatsError>;
  }
>()("@rat-stack/core/FileInspector", {
  make: Effect.gen(function* makeFileInspector() {
    const fileSystem = yield* FileSystem.FileSystem;

}) {
  static readonly layer = Layer.effect(this, this.make);
}

What to notice: Construction needs the dependency; callers need only FileInspector. See service construction¹⁶ for the full pattern.¶

Provide Layers at the entrypoint

The composition root chooses implementations and supplies the application’s services and their dependencies. Give each entrypoint its own root. Our CLI assembles dependencies before running the program.¶

  Effect.provide(
    Layer.mergeAll(
      Layer.provideMerge(FileInspector.layer, NodeServices.layer),
      remoteJoinInterestLayer,
      Approval.denyAll
    )
  )
);

NodeRuntime.runMain(program);

Effect.provide resolves requirements before NodeRuntime.runMain runs the final Effect. See Layer composition¹³.¶

Keep ports inside and adapters outside

Domain code uses a service interface that names the application’s job. Core owns SubscriberIntake; packages/subscriber-delivery implements it. Apps provide that implementation. See hexagonal architecture¹⁹.¶

Keep related definitions with the domain

• Put input, output, and failure schemas in the domain’s contract. Decode at boundaries with Schema¹⁷.¶
• Declare expected failures with useful context. FileStatsError keeps the failed path and filesystem reason. See the error model³⁶.¶
• In rat-stack, a machine²⁰ owns finite modes, cancellation, or legal event sequences. Keep it beside the behavior it controls.¶
• Mirror domain folders in tests. Supply test services through Layers²².¶

House style versus Effect idiom

Where disagreement lives

Sam favors domain folders. Effect leaves folder layout to the application. Sam also calls one API route per file potentially controversial. rat-stack keeps one capability per file and derives routes.¶

A monorepo is one repository containing several packages. Choose monorepo versus single-package layout separately from the service graph.¶

New to Effect? Start with Effect basics¹⁷.¶

Last changed 2026-10-07 in f1a00f2. Source on GitHub. Change log.