53 - Project Structure: Dependency Direction Is the Rule

Previous · Next

Folder names do not impose architecture; imports do. A codebase where any file may import any other becomes a tangle within months: HTTP handlers reach into SQL queries, domain types depend on the ORM, the test suite needs a real database to assert a business rule.

Effect’s service system makes clean boundaries cheap, Context.Service for the interface, Layer for the implementation, but you still need a layout that makes those boundaries visible at a glance. This step pins the four-layer shape and the single rule that governs it.

What you’ll work through

index.test.ts contains three beats: the dependency rule (dependencies point inward only), the four-layer shape (domain / app / adapter / composition), and the composition root where every concrete Layer is assembled into the runtime.

By the end you should be able to glance at any import line in an Effect codebase and tell whether it crosses a boundary the wrong way.

The Rule

Dependencies flow inward. A layer may import from layers it contains; never from layers that contain it.

1
+----------------------------------------------------+
2
|  entrypoints/                                      |
3
|     wires services with Layer.provide              |
4
|     runs the program with runPromise / runFork     |
5
|                                                    |
6
|  +----------------------------------------------+  |
7
|  |  infrastructure/                             |  |
8
|  |     implements interfaces defined in domain  |  |
9
|  |                                              |  |
10
|  |  +----------------------------------------+  |  |
11
|  |  |  application/                          |  |  |
12
|  |  |     orchestrates domain operations     |  |  |
13
|  |  |                                        |  |  |
14
|  |  |  +----------------------------------+  |  |  |
15
|  |  |  |  domain/                         |  |  |  |
16
|  |  |  |     types, rules, service tags   |  |  |  |
17
|  |  |  |     zero external imports        |  |  |  |
18
|  |  |  +----------------------------------+  |  |  |
19
|  |  +----------------------------------------+  |  |
20
|  +----------------------------------------------+  |
21
+----------------------------------------------------+

The Four Layers

`domain/`

Creates the vocabulary: types, validation rules, tagged errors, and the Context.Services that describe what services exist. No imports outside of effect itself.

1
import { Context, Data, Effect, Schema } from "effect"
2

3
export const Order = Schema.Struct({
4
  id: Schema.String,
5
  total: Schema.Number,
6
})
7
export type Order = typeof Order.Type
8

9
export class OrderNotFound extends Data.TaggedError("OrderNotFound")<{
10
  readonly id: string
11
}> {}
12

13
//      ┌─── interface only, no implementation here
14
//      ▼
15
export class OrderRepo extends Context.Service<OrderRepo, {
16
    readonly find: (id: string) => Effect.Effect<Order, OrderNotFound>
17
  }>()("OrderRepo") {}

Details

The service tag lives in domain/ so that application/ (which uses it) and infrastructure/ (which implements it) can both import it without either depending on the other.

`application/`

Orchestrates domain operations into use cases. Imports only from domain/.

1
import { Effect } from "effect"
2
import { OrderRepo } from "../domain/Order.js"
3

4
//      ┌─── Effect<Order, OrderNotFound, OrderRepo>
5
//      ▼
6
export const placeOrder = (id: string) =>
7
  Effect.gen(function* () {
8
    const repo = yield* OrderRepo
9
    return yield* repo.find(id)
10
  })

When to Use

Anywhere a workflow composes multiple domain operations. Use cases stay free of transport details (HTTP status codes, CLI flags) and infrastructure (SQL, S3).

`infrastructure/`

Implements the Context.Services defined in domain/. Imports from domain/ and may also build on application/ helpers.

1
import { Effect, Layer } from "effect"
2
import { OrderRepo, OrderNotFound, type Order } from "../domain/Order.js"
3

4
export const PgOrderRepoLive = Layer.succeed(
5
  OrderRepo,
6
  OrderRepo.of({
7
    find: (id) =>
8
      Effect.tryPromise({
9
        try: () => pgClient.query<Order>("SELECT * FROM orders WHERE id=$1", [id]),
10
        catch: () => new OrderNotFound({ id }),
11
      }),
12
  }),
13
)

Details

Every adapter, Postgres, Stripe, S3, Redis, lives here. Swapping vendors becomes a single-file change because callers only ever know the tag.

`entrypoints/`

The composition root. Reads input, builds the layer graph, runs the effect.

1
import { Effect, Layer } from "effect"
2
import { placeOrder } from "../application/PlaceOrder.js"
3
import { PgOrderRepoLive } from "../infrastructure/PgOrderRepo.js"
4

5
const MainLive = PgOrderRepoLive
6

7
Effect.runPromise(placeOrder("order-1").pipe(Effect.provide(MainLive)))

When to Use

There should be one entrypoint per delivery channel, http.ts, cli.ts, worker.ts. Each is small: parse input, provide the layer, run the effect.

What Goes Where: At a Glance

File	Layer	Allowed Imports
`domain/Order.ts`	`domain`	`effect` only
`domain/OrderRepo.ts` (tag)	`domain`	`effect` only
`application/PlaceOrder.ts`	`application`	`effect`, `domain/*`
`infrastructure/PgRepo.ts`	`infrastructure`	`effect`, `domain/`, `application/`, libs
`entrypoints/http.ts`	`entrypoint`	everything

A Composite Example

1
import { Effect } from "effect"
2
import { OrderRepo } from "../domain/Order.js"
3
import { PaymentService } from "../domain/Payment.js"
4
import { Notifier } from "../domain/Notifier.js"
5

6
//      ┌─── Effect<void, OrderNotFound | PaymentFailed, OrderRepo | PaymentService | Notifier>
7
//      ▼
8
export const checkout = (orderId: string) =>
9
  Effect.gen(function* () {
10
    const orders = yield* OrderRepo
11
    const payment = yield* PaymentService
12
    const notifier = yield* Notifier
13

14
    const order = yield* orders.find(orderId)
15
    yield* payment.charge(order)
16
    yield* notifier.send(order.id)
17
  })

The R channel is the project map: OrderRepo | PaymentService | Notifier. The entrypoint is the only place those three tags become concrete Layers.

A table-driven dependency validator

The four-layer rule is a policy. Writing it as a table — “from each layer, here are the layers it may import” — turns enforcement into a single lookup.

A function over the table is easier to audit than a chain of if-statements and easier to extend when a new layer appears.

1
import { Effect } from "effect"
2

3
type Layer = "domain" | "application" | "infrastructure" | "entrypoint"
4

5
const allowed: Record<Layer, ReadonlyArray<Layer>> = {
6
  domain: [],
7
  application: ["domain"],
8
  infrastructure: ["domain"],
9
  entrypoint: ["domain", "application", "infrastructure"],
10
}
11

12
const checkImport = (from: Layer, to: Layer): Effect.Effect<void, DependencyViolation> =>
13
  allowed[from].includes(to)
14
    ? Effect.void
15
    : Effect.fail(new DependencyViolation({ from, to }))

The table is the policy; the function is a one-line lookup. Adding a fifth layer is a row addition, not a refactor of the validator.

Your turn encode the four-layer policy as a table and write the validator as `allowed[from].includes(to)`. Run it against a known-good import graph and a known-bad one.

Common Pitfalls

1, Importing the implementation instead of the tag. Code in application/ should import OrderRepo (the tag) from domain/, never PgOrderRepo from infrastructure/. The tag is the seam; importing the implementation collapses it.

2, Putting Context.Service in infrastructure/. A tag defined alongside its Postgres implementation forces application/ to reach upward to import it. Move the tag down to domain/ and the dependency arrow flips back inward.

3, Business logic in entrypoints. An HTTP handler that loops, branches, and joins multiple services has stopped being a composition root. Lift the orchestration into application/ and leave the entrypoint as a three-line shim.

4, Skipping the layout for “small” projects. Once a project has more than one delivery channel (HTTP + cron, CLI + worker), the flat structure stops scaling. The four folders cost nothing to introduce on day one.

composition) in the sample project. - [ ] Inspect the composition root: where every concrete Layer is wired into the runtime.

The full test suite

The index.test.ts for this lesson, verbatim from steps/53-project-structure/.

1
import { describe, expect, it } from "vite-plus/test"
2

3
// =============================================================================
4
// 29 - Project Structure: Dependency Direction Is the Rule
5
// =============================================================================
6
//
7
// Layered architecture is a constraint on imports, not on folder names.
8
// This table is the rule; the validator is a one-liner.
9

10
type ModuleKind = "domain" | "application" | "infrastructure" | "entrypoint"
11

12
const allowedDependencies: Record<ModuleKind, ReadonlyArray<ModuleKind>> = {
13
  domain: [],
14
  application: ["domain"],
15
  infrastructure: ["domain", "application"],
16
  entrypoint: ["domain", "application", "infrastructure"],
17
}
18

19
const validateDependency = (from: ModuleKind, to: ModuleKind): string | null =>
20
  allowedDependencies[from].includes(to) ? null : `${from} must not depend on ${to}`
21

22
describe("29 - Project Structure", () => {
23
  // @beat
24
  //   id: dependency-rule
25
  //   shape: one-todo
26
  //   title: Dependencies flow inward
27
  //   teaches: application may import domain; the validator encodes the rule as a table lookup.
28
  //   hint: an allowed dependency returns the same sentinel the validator uses for "no violation"
29
  it("allows application code to depend on domain code", () => {
30
    // Predict the sentinel a valid dependency yields.
31
    expect(validateDependency("application", "domain")).toBe(/* @stub */ null /* @end */)
32
  })
33
  // @end-beat
34

35
  // @beat
36
  //   id: four-layers
37
  //   shape: multi-todo
38
  //   title: Reject outward imports
39
  //   teaches: domain must never import infrastructure; application must never reach up to infrastructure.
40
  //   hint: the violation message follows the pattern `${from} must not depend on ${to}`
41
  it("rejects infrastructure leaking into the domain", () => {
42
    // Predict the violation message the validator returns.
43
    expect(validateDependency("domain", "infrastructure")).toBe(
44
      /* @stub */ "domain must not depend on infrastructure" /* @end */,
45
    )
46
  })
47

48
  it("rejects application reaching up into infrastructure", () => {
49
    expect(validateDependency("application", "infrastructure")).toBe(
50
      /* @stub */ "application must not depend on infrastructure" /* @end */,
51
    )
52
  })
53
  // @end-beat
54

55
  // @beat
56
  //   id: composition-root
57
  //   shape: multi-todo
58
  //   title: Entrypoints compose every layer
59
  //   teaches: The entrypoint is the one place that touches domain, application, and infrastructure to assemble the layer graph.
60
  //   hint: an entrypoint sits on the outside and may depend on every inner layer — each call yields the same "no violation" sentinel
61
  it("treats entrypoints as composition roots", () => {
62
    // Predict the validator result for every entrypoint → inner-layer pairing.
63
    expect(validateDependency("entrypoint", "infrastructure")).toBe(/* @stub */ null /* @end */)
64
    expect(validateDependency("entrypoint", "application")).toBe(/* @stub */ null /* @end */)
65
    expect(validateDependency("entrypoint", "domain")).toBe(/* @stub */ null /* @end */)
66
  })
67
  // @end-beat
68

69
  // @beat
70
  //   id: write-validator
71
  //   shape: one-todo
72
  //   title: Write the dependency validator
73
  //   teaches: Table-driven validation is easier to audit than a chain of if-statements — the allowed imports table is the policy, the function is a single lookup.
74
  //   hint: allowedDependencies[from].includes(to) ? null : `${from} must not depend on ${to}`
75
  it("your turn: implement validateDependency from the table", () => {
76
    const myValidateDependency = (from: ModuleKind, to: ModuleKind): string | null =>
77
      /* @stub */ allowedDependencies[from].includes(to)
78
        ? null
79
        : `${from} must not depend on ${to}` /* @end */
80

81
    expect(myValidateDependency("application", "domain")).toBe(null)
82
    expect(myValidateDependency("domain", "application")).toBe(
83
      "domain must not depend on application",
84
    )
85
    expect(myValidateDependency("infrastructure", "domain")).toBe(null)
86
    expect(myValidateDependency("domain", "infrastructure")).toBe(
87
      "domain must not depend on infrastructure",
88
    )
89
    expect(myValidateDependency("entrypoint", "infrastructure")).toBe(null)
90
  })
91
  // @end-beat
92
})

10·03Project Structure