Aecdm GRAPHQL

Documentation Architecture

📁 instructions/          ← Semantic guidance (HOW to think)
│   00_start_here.md         Core rules, hierarchy, explicit warnings
│   01_query_entry_points.md Valid entry points only
│   02_core_object_model.md  Object hierarchy and traversal
│   03_relationships_vs_properties.md  Critical: Level ≠ property
│   04_property_system.md    Property types and filtering
│   05_versioning_and_time.md Version model
│   06_filters_and_inputs.md Filter input types
│   07_query_patterns.md     Reusable query templates
│
📁 references/            ← Schema reference (WHAT exists)
    ref_00 through ref_10    Field names, argument shapes, types

Document Retrieval Rules

Always Retrieve (Mandatory Foundation)

Before constructing ANY AECDM GraphQL query, retrieve:

Conditionally Retrieve (Trigger-Based)

Prefer Existing Patterns

Before constructing any new query:

1. Retrieve instructions/07_query_patterns.md
2. Find the closest matching pattern
3. Adapt it — do not invent from scratch

Document Role Separation

Use ref_* Documents For:

• Confirming exact field names and argument names
• Verifying input type shapes and required fields
• Checking enum values (Comparators, ExtractionStatus, etc.)
• Validating scalar types (DateTime, PropertyValue, etc.)

Use Instructional (non-ref_*) Documents For:

• Deciding traversal strategy and entry points
• Understanding filter placement and relationship semantics
• Learning anti-patterns and common mistakes
• Choosing between similar approaches

Rule of thumb:

"Use ref_* documents to confirm field names, argument shapes, and valid types. Use non-ref_* documents to decide traversal strategy, filter placement, and relationship semantics."

Critical Constraints

NEVER Do These:

ALWAYS Do These:

Quick Reference: Common Scenarios

Reference Document Index

Anti-Pattern Detection

If you find yourself doing any of these, STOP and re-read the relevant instructional document:

Model Context and Reuse

When a model is loaded via the render-model tool, the response includes the elementGroupId. This ID is required for nearly all AECDM GraphQL queries. The MCP server also stores this value and can return it via get-model-context.

Important: The user can change the loaded model at any time via the hub browser UI without Claude being directly involved. When this happens, the server-side model context is updated and app.updateModelContext() pushes the new context to Claude. However, to guarantee correctness, Claude must always verify the current model context before constructing queries.

Rules for Model Context

Model Context Flow

User asks a query → call get-model-context
                  → GOT elementGroupId: construct query + call execute-query
                  → NO model loaded:    call browse-aecdm to select a model
                                        → then call get-model-context again

MCP Execution Workflow

This skill uses MCP (Model Context Protocol) tools to authenticate and execute queries against the AECDM API.

MCP Tool Reference

execute-query Parameters

Workflow Steps

1. Resolve Model Context → ALWAYS call get-model-context to get the latest elementGroupId
2. Plan Query Chain      → Determine if single or multi-step query needed
3. Construct Query       → Build query following this skill's guidance
4. Execute               → Call execute-query with query + variables
5. Handle Result         → Process success or handle errors

Step-by-step:

1. Resolve model context - Before constructing any query, always call get-model-context to get the current elementGroupId:

   • If it returns an elementGroupId, use it for the query. Do NOT reuse a previously cached value from conversation history — the user may have switched models via the browser.
   • If it returns an error (no model loaded), use browse-aecdm to let the user select a model, then call get-model-context again.

2. Plan the query chain - Analyze the user request to determine if it requires:

   • Single query (e.g., "list all walls")
   • Multi-step chain (e.g., "get all walls on Level 1" requires: get levels → find Level 1 ID → filter elements)

3. Construct query - Build the GraphQL query following this skill's documentation:

   • Retrieve required instructional documents
   • Use validated entry points and filter patterns
   • Check ref_* docs for exact field names

4. Execute - Call execute-query MCP tool with:

   {
     "query": "query GetWalls($elementGroupId: ID!) { elementsByElementGroup(elementGroupId: $elementGroupId, filter: { properties: [{ name: \"Category\", value: [\"Walls\"] }] }) { results { id name } } }",
     "variables": "{\"elementGroupId\": \"your-element-group-id\"}",
     "region": "US"
   }
   

5. Handle result:

   • Success + more queries needed: Extract IDs, construct next query, go to step 3
   • Success + done: Return final results to user
   • Success + visual feedback needed: Call highlight-elements with external IDs to filter/highlight in the viewer
   • Error: Go to Error Handling section

Error Handling

When a query fails, follow this error correction loop:

Error Correction Loop

1. Parse Error      → Extract error message from response
2. Identify Issue   → Determine error type (field, filter, auth, etc.)
3. Consult Docs     → Find correct syntax in ref_* documents
4. Fix Query        → Apply correction to query
5. Retry            → Execute again (max 3 attempts)

Error Type Reference

Error Response Format

The execute-query tool returns errors in this format:

{
  "errors": [
    { "message": "Cannot query field \"invalidField\" on type \"Element\"" }
  ]
}

Fix Strategy

1. Parse the error message to identify the problematic field, argument, or syntax
2. Locate the relevant reference document based on what you're querying
3. Find the correct syntax in the reference document
4. Update the query with the correction
5. Retry execution - do not exceed 3 attempts for the same error type

Multi-Step Query Chaining

Many user requests require multiple queries where results from one query feed into the next.

Common Query Chains

Chaining Workflow

┌─────────────────┐
│  User Request   │
└────────┬────────┘
         ▼
┌─────────────────┐
│ Plan Query Chain│  ← Determine all queries needed
└────────┬────────┘
         ▼
┌─────────────────┐
│ Execute Query 1 │
└────────┬────────┘
         ▼
┌─────────────────┐
│  Extract IDs    │  ← Pull IDs from results for next query
└────────┬────────┘
         ▼
┌─────────────────┐
│ Execute Query 2 │  ← Use extracted IDs as variables
└────────┬────────┘
         ▼
    (repeat as needed)
         ▼
┌─────────────────┐
│  Return Results │
└─────────────────┘

Example: Get All Walls on Level 1

Important: Do not assume a level name like "Level 1" or "Ground Floor" exists. Always discover levels first by querying with Category = Levels, then pick the best match from the results.

Step 1: Discover levels and find the target level's element ID

query DiscoverLevels($elementGroupId: ID!) {
  elementsByElementGroup(elementGroupId: $elementGroupId, 
    filter: { 
      properties: [{ name: "Category", value: ["Levels"] }]
    }) {
    results { id name }
  }
}

Variables: {"elementGroupId": "your-element-group-id"}

Pick the level that best matches the user's intent (e.g. "Level 1") from the returned results.

Step 2: Extract the Level ID from results

{
  "data": {
    "elementsByElementGroup": {
      "results": [{ "id": "level-1-element-id", "name": "Level 1" }]
    }
  }
}

Step 3: Query walls filtered by Level reference

query GetWallsOnLevel($elementGroupId: ID!, $levelId: String!) {
  elementsByElementGroup(elementGroupId: $elementGroupId,
    filter: {
      properties: [{ name: "Category", value: ["Walls"] }],
      references: [{ name: "Level", referenceId: [$levelId] }]
    }) {
    results { id name properties { results { name value } } }
  }
}

Variables: {"elementGroupId": "your-element-group-id", "levelId": "level-1-element-id"}

ID Extraction Patterns