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

Effect keeps the surfaces on one contract

An Effect Schema defines accepted values and provides types and runtime checks. Our shared contract describes one action’s input, output, failures, and metadata. Effect Schema owns inputs, outputs, and failures in our shared contract. implement.ts binds the handler and its approval requirement.¶

A projection builds an interface from a capability, a named action with a contract and handler. The HTTP projection creates an Effect HttpApi. Other projections create CLI commands and an AI toolkit from the same contracts.¶

apps/cli/src/surfaces.ts and apps/site/src/app.ts supply implementations with Layers.¶

Follow one interface at a time

• MCP is another surface²⁷: discover and call the toolkit over the protocol.¶
• OpenAPI describes the refusal too¹⁵: derive the HTTP document and declare the bodyless decode failure.¶
• One schema, three surfaces²³: project the contract instead of maintaining three schemas.¶
• Schemas define the boundary¹⁷: decode unknown values and keep domain refusals typed.¶
• One program can replace several tool calls²¹: combine content capabilities without widening their authority.¶

Layer supplies the job

packages/core/src/join-intake.ts builds a Layer.effect(JoinInterest, ...). It captures the ticket, scoring, events, contact store, delivery, and token services. It then returns the submission method.¶

Source: packages/core/src/join-intake.ts at a646f7ffd00273d85fbe1d905d9cdb194fdc0f60, lines 58–64.¶

    ): Effect.fn.Return<JoinOutput> {
      const statusRef = yield* newStatusRef;
      const answer = { message: JOIN_ANSWER, statusRef } as const;

      if (intake.agent?.enabled !== true) {
        return { message: JOIN_NOT_OPEN, statusRef };
      }

Effect’s Layer.provide supplies a Layer’s dependencies. HttpApiBuilder.layer registers HTTP routes and can expose OpenAPI¹⁵. Neither requires a second domain handler.¶

One capability, every surface¹⁸ states the house rule⁹. Hexagonal architecture¹⁹ names the adapter boundary. The fence³⁹ enforces it.¶

The peers page records other Effect and Alchemy projects, whose designs can differ.¶

Start with Effect basics¹⁷, then construct a service¹⁶ and compose its Layers¹³.¶

See also: Structure an Effect codebase by domain¹⁶.¶

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.