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	Purpose	Example
constructorParams	Fields stored on the instance	["projectId", "screenId"]
reference	Identity-map keys (.id aliases the LAST key)	{ "keys": ["projectId", "screenId"] }
parentField	Which param is injected from a parent class	"projectId"
factories	Local factory methods (no API call)	[{ "method": "project", "returns": "Project" }]
sideEffects	Handwritten extension methods (declared, never generated)	[{ "method": "upload", "reason": "private_rest", "specPath": "src/spec/upload.ts" }]
extensionPath	Module re-exporting the class with handwritten methods	"../../src/project-ext.js"

[!IMPORTANT] The IR schema is STRICT. Unknown keys are hard validation errors, not silently ignored. Per-field source-mapping helpers described in older docs were never implemented and do not exist — identity fields are populated by the EntityManager from reference.keys, resource name parsing, and id fallback. If validation rejects a key you expected to exist, the feature does not exist — do not work around it.

---

Designing Bindings

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

Arg routing

Type	Meaning	Code generated
self	From this.field	projectId: this.projectId
param	From method parameter	prompt: prompt
computed	template interpolation ("template": "projects/{projectId}")	name: \projects/${this.projectId}/screens/${screenId}``
selfArray	Wrap self field as array	selectedScreenIds: [this.screenId]

Optional params use "optional": true. Renamed params use "rename": "newName". A "default": "VALUE" (requires optional: true) is sent when the caller omits the value: deviceType: options?.deviceType ?? "DESKTOP".

[!IMPORTANT] Method signature shape (D12): required params are positional, in IR order; ALL optional params are emitted into a single trailing options?: { ... } object. generate(prompt, options?), never generate(prompt, deviceType?).

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; find?: string; acknowledgeSingle?: boolean }

Projection	Generated code	Use when
[] (empty)	raw	Direct return (whole response)
[{ "prop": "projects" }]	raw.projects	Array inside object
[{ "prop": "outputComponents", "index": 0 }, { "prop": "design" }, { "prop": "screens", "index": 0 }]	raw.outputComponents[0].design.screens[0]	Deeply nested single item
[{ "prop": "outputComponents", "each": true }, { "prop": "design" }, { "prop": "screens", "each": true }]	flatMap chain	Collect all items across arrays
[{ "prop": "screenshot" }, { "prop": "downloadUrl" }]	raw.screenshot.downloadUrl	Navigate nested properties

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. "find": "a.b" scans an array for the first element whose nested path is non-null.

[!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. Stepping THROUGH an array without index/each/find is also a codegen error — the emitted chain would be undefined at runtime.

[!WARNING] Truncation lint: using index or find on an UNBOUNDED array emits a warning — every other element is silently dropped (this exact pattern caused project.generate() to return one screen of many). Prefer "each": true + "array": true. Only if the result is semantically singular, acknowledge it with "acknowledgeSingle": true on the step.

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