# effect-ts/effect architecture

> Architecture diagram of the GitHub repository effect-ts/effect, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/effect-ts/effect
- Repository: https://github.com/effect-ts/effect

## Overview

Effect is a TypeScript library and monorepo for constructing typed, resource-safe application workflows. The central workflow is to compose an Effect, provide its required services through Layers, execute it with the runtime, and inspect its success or failure. The repository also supplies domain libraries for AI, clustering, HTTP, SQL, platform runtimes, and observability integrations. The README documents package roles; sampled core and cluster sources support only the specific internal relationships shown below, so other links are omitted where wiring was not evidenced.

Main entry points: [`packages/effect/src/Effect.ts`](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Effect.ts) (Effect Programs), [`packages/effect/src/internal/effect.ts`](https://github.com/effect-ts/effect/blob/main/packages/effect/src/internal/effect.ts) (Effect Runtime), [`packages/effect/src/Layer.ts`](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Layer.ts) (Service Layers), [`packages/effect/src/Exit.ts`](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Exit.ts) (Execution Result)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Effect Runtime"]
  node_effect["Effect Programs<br/>[Effect.ts]"]
  node_runtime["Effect Runtime<br/>[effect.ts]"]
  node_layers["Service Layers<br/>[Layer.ts]"]
  node_context["Service Context<br/>[Context.ts]"]
  node_fiber["Fibers<br/>[Fiber.ts]"]
  node_scope["Resource Scopes<br/>[Scope.ts]"]
  node_schedule["Schedules<br/>[Schedule.ts]"]
  node_exit["Execution Result<br/>[Exit.ts]"]
end

subgraph group_domain["Domain Capabilities"]
  node_schema["Schema Validation<br/>[Schema.ts]"]
  node_streams["Streams and Channels<br/>[Stream.ts]"]
  node_http["HTTP APIs<br/>[HttpApi.ts]"]
  node_ai["AI Modules<br/>[LanguageModel.ts]"]
  node_cluster["Cluster Entities"]
  node_message["Cluster Messaging<br/>[MessageStorage.ts]"]
end

subgraph group_integrations["Provider Integrations"]
  node_ai_providers["AI Providers"]
  node_otel["OpenTelemetry<br/>[NodeSdk.ts]"]
end

subgraph group_platform["Platform and Data"]
  node_platform["Runtime Platforms"]
  node_sql["SQL Clients"]
end

node_developer(("Application Developer"))
node_developer_result(("Application Outcome"))

node_developer -->|"composes"| node_effect
node_effect -->|"executes"| node_runtime
node_effect -->|"accepts services"| node_layers
node_layers -->|"builds services"| node_context
node_effect -.->|"forks work"| node_fiber
node_effect -.->|"manages lifetime"| node_scope
node_effect -.->|"retries work"| node_schedule
node_runtime -->|"produces result"| node_exit
node_effect -.->|"validates data"| node_schema
node_effect -.->|"composes streams"| node_streams
node_effect -.->|"serves APIs"| node_http
node_effect -.->|"builds AI workflows"| node_ai
node_effect -->|"runs clustered workflows"| node_cluster
node_cluster -->|"stores messages"| node_message
node_ai -->|"connects providers"| node_ai_providers
node_developer -->|"adds telemetry"| node_otel
node_developer -->|"uses runtime services"| node_platform
node_developer -->|"uses database clients"| node_sql
node_exit -->|"returns outcome"| node_developer_result

click node_effect "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Effect.ts"
click node_runtime "https://github.com/effect-ts/effect/blob/main/packages/effect/src/internal/effect.ts"
click node_layers "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Layer.ts"
click node_context "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Context.ts"
click node_fiber "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Fiber.ts"
click node_scope "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Scope.ts"
click node_schedule "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Schedule.ts"
click node_exit "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Exit.ts"
click node_schema "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Schema.ts"
click node_streams "https://github.com/effect-ts/effect/blob/main/packages/effect/src/Stream.ts"
click node_http "https://github.com/effect-ts/effect/blob/main/packages/effect/src/http-api/HttpApi.ts"
click node_ai "https://github.com/effect-ts/effect/blob/main/packages/effect/src/ai/LanguageModel.ts"
click node_cluster "https://github.com/effect-ts/effect/blob/main/packages/effect/src/cluster/ClusterWorkflowEngine.ts"
click node_message "https://github.com/effect-ts/effect/blob/main/packages/effect/src/cluster/MessageStorage.ts"
click node_ai_providers "https://github.com/effect-ts/effect/tree/main/packages/ai"
click node_otel "https://github.com/effect-ts/effect/blob/main/packages/opentelemetry/src/NodeSdk.ts"
click node_platform "https://github.com/effect-ts/effect/tree/main/packages/platform"
click node_sql "https://github.com/effect-ts/effect/tree/main/packages/sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_effect,node_runtime,node_layers,node_context,node_fiber,node_scope,node_schedule,node_exit toneBlue
class node_schema,node_streams,node_http,node_ai,node_cluster,node_message toneAmber
class node_ai_providers,node_otel toneMint
class node_platform,node_sql toneRose
class node_developer,node_developer_result toneIndigo
```

## Components

### Effect Runtime

- [Effect Programs](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Effect.ts): `packages/effect/src/Effect.ts`
- [Effect Runtime](https://github.com/effect-ts/effect/blob/main/packages/effect/src/internal/effect.ts): `packages/effect/src/internal/effect.ts`
- [Service Layers](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Layer.ts): `packages/effect/src/Layer.ts`
- [Service Context](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Context.ts): `packages/effect/src/Context.ts`
- [Fibers](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Fiber.ts): `packages/effect/src/Fiber.ts`
- [Resource Scopes](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Scope.ts): `packages/effect/src/Scope.ts`
- [Schedules](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Schedule.ts): `packages/effect/src/Schedule.ts`
- [Execution Result](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Exit.ts): `packages/effect/src/Exit.ts`

### Domain Capabilities

- [Schema Validation](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Schema.ts): `packages/effect/src/Schema.ts`
- [Streams and Channels](https://github.com/effect-ts/effect/blob/main/packages/effect/src/Stream.ts): `packages/effect/src/Stream.ts`
- [HTTP APIs](https://github.com/effect-ts/effect/blob/main/packages/effect/src/http-api/HttpApi.ts): `packages/effect/src/http-api/HttpApi.ts`
- [AI Modules](https://github.com/effect-ts/effect/blob/main/packages/effect/src/ai/LanguageModel.ts): `packages/effect/src/ai/LanguageModel.ts`
- [Cluster Entities](https://github.com/effect-ts/effect/blob/main/packages/effect/src/cluster/ClusterWorkflowEngine.ts): `packages/effect/src/cluster/ClusterWorkflowEngine.ts`
- [Cluster Messaging](https://github.com/effect-ts/effect/blob/main/packages/effect/src/cluster/MessageStorage.ts): `packages/effect/src/cluster/MessageStorage.ts`

### Provider Integrations

- [AI Providers](https://github.com/effect-ts/effect/tree/main/packages/ai): `packages/ai`
- [OpenTelemetry](https://github.com/effect-ts/effect/blob/main/packages/opentelemetry/src/NodeSdk.ts): `packages/opentelemetry/src/NodeSdk.ts`

### Platform and Data

- [Runtime Platforms](https://github.com/effect-ts/effect/tree/main/packages/platform): `packages/platform`
- [SQL Clients](https://github.com/effect-ts/effect/tree/main/packages/sql): `packages/sql`

### Other components

- **Application Developer**
- **Application Outcome**

## Connections

- Application Developer → Effect Programs: composes (evidence: `README.md`)
- Effect Programs → Effect Runtime: executes (evidence: `packages/effect/src/Effect.ts`)
- Effect Programs → Service Layers: accepts services (evidence: `packages/effect/src/Effect.ts`)
- Service Layers → Service Context: builds services (evidence: `packages/effect/src/Layer.ts`)
- Effect Programs → Fibers: forks work (evidence: `packages/effect/src/Effect.ts`)
- Effect Programs → Resource Scopes: manages lifetime (evidence: `packages/effect/src/Effect.ts`)
- Effect Programs → Schedules: retries work (evidence: `packages/effect/src/Effect.ts`)
- Effect Runtime → Execution Result: produces result (evidence: `packages/effect/src/Exit.ts`)
- Effect Programs → Schema Validation: validates data
- Effect Programs → Streams and Channels: composes streams
- Effect Programs → HTTP APIs: serves APIs
- Effect Programs → AI Modules: builds AI workflows
- Effect Programs → Cluster Entities: runs clustered workflows (evidence: `packages/effect/src/cluster/ClusterWorkflowEngine.ts`)
- Cluster Entities → Cluster Messaging: stores messages (evidence: `packages/effect/src/cluster/MessageStorage.ts`)
- AI Modules → AI Providers: connects providers (evidence: `README.md`)
- Application Developer → OpenTelemetry: adds telemetry (evidence: `README.md`)
- Application Developer → Runtime Platforms: uses runtime services (evidence: `README.md`)
- Application Developer → SQL Clients: uses database clients (evidence: `README.md`)
- Execution Result → Application Outcome: returns outcome (evidence: `packages/effect/src/Exit.ts`)
