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 b4d6b8f499e57bc76914ad70df3a0c99751ae28c, lines 55–69.¶

export const joinIntakeLayer = Layer.effect(
  JoinInterest,
  Effect.gen(function* makeJoinIntake() {
    const tickets = yield* IntakeTicket;
    const scorer = yield* AbuseScore;
    const events = yield* IntakeEvents;
    const contacts = yield* JoinContactStore;
    const intake = yield* SubscriberIntake;
    const tokens = yield* InterestTokens;
    const crypto = yield* Crypto.Crypto;

    const submit = Effect.fn("JoinInterest.submit")(function* submit(
      input: JoinInput
    ): Effect.fn.Return<JoinOutput> {
      const statusRef = yield* newStatusRef;

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-18 in e5c3077. Source on GitHub. Change log.