BlueprintStep

BlueprintStep records a single atomic action taken by the Blueprint Analyzer AI agent during a web-navigation run. Each step belongs to exactly one BlueprintRun (cascade-deleted with it) and is sequenced by a monotonically increasing step_number. Steps capture the agent’s reasoning, the page URL at the time of execution, the action it chose (e.g. click, type, scroll), structured action parameters, the raw LLM response, screenshot storage references, and an outcome flag — forming the complete execution trace for a run. The table is written exclusively by the blueprint-analyzer.service.ts pipeline; no user-facing PATCH endpoint exists.

Naming	Value
Object	BlueprintStep
Resource type (JSON:API `type`)	`blueprint_step`
Collection / records root	— _{(not a records root)}
REST base	`/v1/blueprint-steps`
Entity class	`BlueprintStep`

Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.

API operations

Operation	Method & path	Status
List	`GET /v1/blueprint-steps`	🟡 Planned
Retrieve	`GET /v1/blueprint-steps/{id}`	🟡 Planned
Create	`POST /v1/blueprint-steps`	🟡 Planned
Update	`PATCH /v1/blueprint-steps/{id}`	🟡 Planned
Delete	`DELETE /v1/blueprint-steps/{id}`	🟡 Planned

Data model

Attributes

Field	Type	Required	Constraints	Allowed values	Description
blueprint_step_id	string (UUID) 🔒 system	✅ Yes	unique; generated by gen_random_uuid() at INSERT	Any valid UUID v4	Public-facing stable identifier for the step. Exposed as the JSON:API `id`. Never reused.
step_number	integer	✅ Yes	composite UNIQUE (blueprint_run_pk, step_number); composite partial index idx_blueprint_steps_run_step on (blueprint_run_pk, step_number) WHERE deleted_at IS NULL	Positive integer; 1-based sequence assigned by the analyzer service	1-based ordinal position of this step within its parent run. Uniqueness is enforced at the DB level per run (soft-delete-aware index).
action_type	string (text)	✅ Yes	NOT NULL	Free-form string set by the analyzer (e.g. ‘click’, ‘type’, ‘scroll’, ‘navigate’, ‘extract’, ‘wait’)	Identifies the category of browser action the agent decided to execute at this step.
reasoning	string (text)	⚪ No	nullable	—	Free-text chain-of-thought produced by the LLM before committing to this action. Populated when the model includes a reasoning block in its response.
page_url	string (text)	✅ Yes	NOT NULL	Full URL of the page at the time the step was executed	Captures the browser’s current URL when the step fired, enabling replay and debugging.
screenshot_path	string (text)	⚪ No	nullable	GCS object path relative to the bucket, or null if no screenshot was captured	Path of the screenshot image stored in GCS at the time of this step. Paired with screenshot_bucket to form the full storage reference.
screenshot_bucket	string (text)	⚪ No	nullable	GCS bucket name, or null	GCS bucket that holds the screenshot referenced by screenshot_path. Null when no screenshot was taken for this step.
action_details	jsonb	⚪ No	nullable	Arbitrary JSON object; shape depends on action_type (e.g. selector, coordinates, input text, scroll delta)	Structured parameters needed to replay or audit the exact action that was executed (e.g. CSS selector, click coordinates, text typed).
ai_response	jsonb	⚪ No	nullable	Arbitrary JSON; typically the raw Anthropic API response object	Full LLM response payload recorded for observability — includes model ID, stop_reason, token usage, and tool calls. Enables cost analysis and debugging.
dom_summary_length	integer	⚪ No	nullable	Non-negative integer representing character count of the DOM summary sent to the LLM	Character length of the DOM summary fed to the model for this step. Useful for prompt-size analytics and detecting pages with unusually large DOMs.
action_success	boolean	⚪ No	nullable	true \| false \| null	Whether the browser action completed without error. Null means the outcome was not recorded (e.g. the step was interrupted). false indicates the browser threw an exception, detailed in action_error.
action_error	string (text)	⚪ No	nullable	Error message string, or null	Human-readable error message when action_success is false. Captures Playwright/browser errors (selector not found, navigation timeout, etc.).
created_at	timestamptz 🔒 system	✅ Yes	NOT NULL; set by onCreate hook to new Date()	—	Timestamp when the row was inserted. Set automatically at creation; never updated.
updated_at	timestamptz 🔒 system	⚪ No	nullable; set by onCreate and onUpdate hooks	—	Timestamp of the last mutation. Set automatically at creation and on every update by MikroORM lifecycle hooks.
deleted_at	timestamptz 🔒 system	⚪ No	nullable	null (active) \| ISO 8601 timestamp (soft-deleted)	Soft-delete sentinel. Non-null means the row is logically deleted. The partial index idx_blueprint_steps_run_step covers only rows WHERE deleted_at IS NULL.

Relationships

Name	Type	Required	Description
blueprint_run	to-one (ManyToOne)	Yes — NOT NULL FK with ON DELETE CASCADE	The parent BlueprintRun that owns this step. Deleting the run cascades and hard-deletes all its steps. This is the only relationship declared on BlueprintStep itself; the inverse collection (steps) is declared on BlueprintRun.

System-computed

blueprint_step_id — generated by gen_random_uuid() at INSERT, never caller-supplied
created_at — set to new Date() by MikroORM onCreate hook
updated_at — set to new Date() by both onCreate and onUpdate hooks
deleted_at — soft-delete sentinel; written by the service layer when soft-deleting a step or its parent run
step_number — assigned by blueprint-analyzer.service.ts before INSERT; not derived from a DB sequence but from the service’s step counter
Cascade delete — when the parent BlueprintRun is deleted (hard or via cascade), all BlueprintStep rows are hard-deleted by the DB foreign-key constraint (ON DELETE CASCADE)

Example

{
  "data": {
    "id": "7e4c1a2b-d3f0-4e8a-b5c6-9d0e1f2a3b4c",
    "type": "blueprint_step",
    "attributes": {
      "blueprint_step_id": "7e4c1a2b-d3f0-4e8a-b5c6-9d0e1f2a3b4c",
      "step_number": 3,
      "action_type": "click",
      "reasoning": "The login button is visible and I need to authenticate before accessing the invoices page.",
      "page_url": "https://app.example.com/login",
      "screenshot_path": "blueprint-runs/run_abc123/step_003.png",
      "screenshot_bucket": "well-blueprints-prod",
      "action_details": {
        "selector": "#login-submit-btn",
        "coordinates": { "x": 640, "y": 420 }
      },
      "ai_response": {
        "model": "claude-opus-4-6",
        "stop_reason": "tool_use",
        "usage": { "input_tokens": 4120, "output_tokens": 87 }
      },
      "dom_summary_length": 8432,
      "action_success": true,
      "action_error": null,
      "created_at": "2026-02-24T14:23:01.000Z",
      "updated_at": "2026-02-24T14:23:02.000Z",
      "deleted_at": null
    },
    "relationships": {
      "blueprint_run": {
        "data": { "type": "blueprint_run", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
      }
    }
  }
}

_{Source: apps/api/src/database/entities/BlueprintStep.ts · domain: automation · tier: Activity}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example