feat: OpenAPI-to-Digital-Twin scaffolding skill

[AlexMikhalev]

Summary

Create a terraphim skill that scaffolds a new digital twin (mock API server) crate from an OpenAPI specification. This connects the digital-twins platform (zestic-ai/digital-twins) with terraphim's knowledge graph and ontology capabilities.

Context

The digital-twins project provides high-fidelity Rust-based mock servers for third-party APIs (Resend, Stripe, Zoho CRM, GitHub Auth, Google Auth). Currently, adding a new API twin requires manual crate creation, route definition, and state store setup. The Resend twin took a full spec-driven cycle to reach 100% coverage (59 endpoints).

An OpenAPI-to-twin skill would automate the repetitive scaffolding, letting developers focus on behavior fidelity rather than boilerplate.

Proposed Skill: generate-api-twin

Input

• OpenAPI 3.x specification (JSON or YAML)
• Service name (e.g., stripe, zoho-crm)
• Optional: authentication pattern (bearer, api-key, oauth)

Output

• Rust crate scaffold: crates/twin-{name}/
  • src/lib.rs -- router with all endpoints from spec
  • src/state.rs -- DashMap stores for each resource type
  • src/resources/ -- handler modules per resource group
  • src/auth.rs -- authentication middleware matching the API's auth pattern
• Route registration in twin-server/src/main.rs
• Spec file placement in specs/{name}/
• Verification matrix template (spec requirement -> implementation -> test)

Patterns to Follow

From twin-core:

• DashMapStore<T> with HasId trait for all resources
• generate_id(prefix) for consistent ID generation
• TwinError for HTTP error responses
• EventBus integration for webhook/event resources
• PaginatedResponse<T> for list endpoints

Phases

1. Parse OpenAPI spec -- Extract paths, methods, request/response schemas, auth requirements
2. Generate Rust types -- Convert JSON Schema types to Rust structs with serde derives
3. Generate route handlers -- CRUD handlers per resource, matching HTTP methods from spec
4. Generate state stores -- DashMap stores for each resource type identified in spec
5. Generate tests -- Basic integration tests for each endpoint (create, read, list, delete)
6. Wire into server -- Add feature flag and router mounting in twin-server

Integration with terraphim KG

The skill could use terraphim's concept matching to:

• Map API domain terms to existing knowledge graph concepts
• Identify overlapping resources across twins (e.g., "customer" in Stripe vs "contact" in Zoho CRM)
• Generate domain model entries for the API's resource taxonomy

Acceptance Criteria

• Skill accepts OpenAPI 3.x spec and produces compilable Rust crate
• Generated crate follows twin-core patterns (DashMapStore, TwinError, generate_id)
• Generated routes match all paths/methods from input spec
• Generated types are serde-compatible with real API responses
• Feature flag is added to twin-server Cargo.toml
• Basic integration tests are generated and pass

References

• Digital twins repo: https://github.com/zestic-ai/digital-twins
• twin-core patterns: crates/twin-core/src/ (DashMapStore, EventBus, TwinError)
• Resend twin (reference implementation): crates/twin-resend/ (59 endpoints, 100% coverage)
• Verification report: VERIFICATION_REPORT.md