stitch-sdk-domain-design

Stitch SDK Domain Design

This skill teaches you how to perform Stage 2 of the generation pipeline: reading tool schemas and producing domain-map.json — the intermediate representation that drives codegen.

Your Inputs

1. tools-manifest.json — raw MCP tool schemas captured from the server (includes outputSchema)
2. ir-schema.ts — Zod schema defining valid domain-map structure (the canonical contract)
3. Existing domain-map.json — the current IR (if extending, not starting fresh)
4. The stitch-sdk-development skill — for understanding the pipeline context

Your Output

A valid domain-map.json with two sections: classes and bindings, validated by ir-schema.ts.

[!IMPORTANT] Your output is validated twice by the codegen: structurally (Zod IR schema) and semantically (projection steps verified against outputSchema from the tools-manifest).

Designing Classes

Each class represents a domain entity. Ask: "What noun does the user interact with?"

{
  "Stitch": {
    "description": "Main entry point. Manages projects.",
    "constructorParams": [],
    "isRoot": true,
    "factories": [
      {
        "method": "project",
        "returns": "Project",
        "description": "Create a Project handle from an ID."
      }
    ]
  }
}

Key decisions:

Field Mapping

Use fieldMapping when a param needs a different source field, prefix stripping, or a fallback:

{
  "constructorParams": ["projectId", "screenId"],
  "fieldMapping": {
    "projectId": { "from": "name", "stripPrefix": "projects/" },
    "screenId": {
      "from": "id",
      "fallback": { "field": "name", "splitOn": "/screens/" }
    }
  }
}

• stripPrefix: Removes a resource name prefix from the value
• fallback: If the primary field is missing, splits an alternate field on a delimiter

Designing Bindings

Each binding maps one MCP tool to one class method. Ask: "Who owns this action?"

Arg routing

Optional params use "optional": true. Renamed params use "rename": "newName".

Response Projections

The returns.projection array tells codegen how to navigate the API response. Each step is a ProjectionStep:

{ prop: string; index?: number; each?: boolean; fallback?: string }

Decision: Use "index": 0 when extracting a single item. Use "each": true when collecting all items (array result). You cannot use both on the same step.

[!TIP] Every prop in a projection is validated against the tool's outputSchema at codegen time. If you typo a property name, codegen will fail with a diagnostic listing the available properties.

Return class wrapping

When returns.class is set, the extracted data is wrapped in a domain class constructor:

{
  "returns": {
    "class": "Screen",
    "projection": [{ "prop": "screens" }],
    "array": true
  }
}

The codegen automatically spreads parentField into the data if the child class declares one.

Cache-aware methods

Add a cache field with a structured projection to check this.data before calling the API:

{
  "cache": {
    "projection": [{ "prop": "htmlCode" }, { "prop": "downloadUrl" }],
    "description": "Use cached HTML download URL from generation response if available"
  }
}

When the cached property is a nested object (like File with a downloadUrl), use multiple projection steps to drill into it.

Generated code:

if (this.data?.htmlCode?.downloadUrl) return this.data?.htmlCode?.downloadUrl;
// ... else call API

Decision Framework

When mapping a new tool, answer these questions:

1. Which class? Look at which fields the tool requires. If it needs projectId from self, it belongs on Project or Screen. If it needs nothing from self, it belongs on Stitch.

2. Which method name? Use the verb from the tool name, simplified. generate_screen_from_text → generate. edit_screens → edit.

3. Arguments from self or param? If the caller already has the data (because they're calling a method on themselves), use self. If they need to provide it, use param.

4. How deep is the return? Check the tool's outputSchema in tools-manifest.json. Build the projection array step-by-step to navigate to the useful data.

5. Should it cache? If the data is available from a previous response (like generation), add a cache field with the projection path.

Validation

After editing domain-map.json:

bun scripts/generate-sdk.ts     # Validates IR + projections, then generates
npx tsc --noEmit                 # Type check
npx vitest run                   # Unit tests
bun scripts/e2e-test.ts          # E2E tests
bun scripts/validate-generated.ts  # Lock integrity

If a projection is invalid, you'll see:

❌ Binding "Project.generate" projection step 2:
   property "screenz" not found in outputSchema.
   Available properties: screens, components, metadata