SUI Architect

Transform ideas into complete SUI Move project architectures and specifications.

Overview

This skill guides you from a rough idea to a complete, well-documented architecture through:

•Guided questioning (one question at a time)
•Project type templates (DeFi, NFT, GameFi, DAO, etc.)
•Best practice references from similar projects
•SUI ecosystem tool integration suggestions
•Comprehensive specification document generation

Quick Start

bash

# Start architecture planning
sui-architect

# Or called by main orchestrator
sui-full-stack  # → Phase 1: Architecture

SUI v1.65 Architecture Considerations (Protocol 110)

When designing architectures, account for these recent platform changes:

•Protocol Version 110 (testnet v1.65.1, February 2026)
•Data Access: gRPC (GA, primary), GraphQL (beta, frontend/indexer), JSON-RPC (deprecated, removed April 2026)
•Balance API Split: coinBalance (fungible coins only) and addressBalance (all balance types)
•TxContext Flexible Positioning: Entry functions no longer require TxContext as the last parameter.
•poseidon_bn254: Available on all networks for zero-knowledge proof applications.
•Address Alias (Testnet): Human-readable address mappings available on testnet. Plan for mainnet availability.
•Entry Function Changes: Signature check disabled; non-public entry functions cannot have hot-potato-entangled arguments.
•DeepBook Explicit Dependency: Since v1.47, DeepBook must be added explicitly to Move.toml.
•SDK Naming: @mysten/sui (not @mysten/sui.js), Transaction (not TransactionBlock)

Core Workflow

Phase 1: Project Type Identification

Ask user about their project type:

code

What type of project are you building?
  A) DeFi (AMM, Lending, Staking, Derivatives)
  B) NFT (Marketplace, Gaming, Collectibles)
  C) GameFi (On-chain game logic, Asset management)
  D) DAO (Governance, Treasury, Voting)
  E) Infrastructure (Oracle, Bridge, Identity)
  F) Custom (Mixed or innovative type)

Then narrow down to specific sub-type based on selection.

Phase 2: Template Selection

Based on project type, load starter template with:

•Module structure
•Common objects/capabilities
•Recommended SUI tools

Available templates: nft-marketplace, defi-amm, gamefi, dao, infrastructure

See templates/ for all available templates.

Phase 3: Requirements Exploration

Ask questions one at a time to refine architecture:

•User roles and permissions
•Core features needed
•NFT/token standards (if applicable)
•Payment methods
•Storage strategy (on-chain, Walrus, IPFS)
•Upgradeability requirements
•Emergency controls

Important: Ask ONE question at a time, wait for answer, then proceed.

Phase 4: Ecosystem Tool Integration

Suggest relevant SUI tools based on requirements:

•Storage needed → sui-walrus
•Authentication → sui-zklogin or sui-passkey
•NFT trading → sui-kiosk
•DEX integration → sui-deepbook
•Name service → sui-suins
•Cross-chain → sui-nautilus

Query latest integration patterns:

typescript

const info = await sui_docs_query({
  type: "docs",
  target: "kiosk",
  query: "Transfer policy implementation"
});

Phase 5: Best Practice References

Query similar projects for patterns:

typescript

const references = await sui_docs_query({
  type: "github",
  target: "sui-core",
  query: "NFT marketplace example Kiosk",
  options: {
    include_examples: true
  }
});

Phase 6: Architecture Design Presentation

Present design in small sections (200-300 words each):

•System Overview
•Module Architecture
•Data Structures
•Core Functions
•Permission System (Capabilities)
•Event System
•Error Handling
•Security Considerations
•Tool Integration Plan
•Testing Strategy
•Deployment Plan
•Gas Optimization

After each section, ask: "Does this look good?"

Wait for confirmation before proceeding to next section.

Phase 7: Specification Document Generation

Generate comprehensive spec at:

code

docs/specs/YYYY-MM-DD-[project-name]-spec.md
docs/architecture/module-dependency.mmd
docs/architecture/data-flow.mmd
docs/security/threat-model.md
README.md

See examples.md for complete specification template.

Output Files

Main spec: docs/specs/YYYY-MM-DD-project-spec.md

Contains:

•Executive Summary
•Architecture Overview (with diagrams)
•Module Design
•Data Models
•API Specification
•Security Considerations
•Integration Guide (SUI tools)
•Testing Strategy
•Deployment Plan
•Appendix (references, versions)

Additional files:

•docs/architecture/overview.md - High-level architecture
•docs/architecture/module-dependency.mmd - Mermaid dependency diagram
•docs/architecture/data-flow.mmd - Data flow diagram
•docs/security/threat-model.md - Threat analysis
•README.md - Project overview

Configuration

.sui-architect.json:

json

{
  "output_dir": "docs/specs",
  "templates": {
    "use_builtin": true,
    "custom_path": null
  },
  "validation": {
    "check_similar_projects": true,
    "query_latest_docs": true,
    "max_questions": 20
  },
  "docs": {
    "generate_mermaid": true,
    "generate_api_docs": true,
    "include_security_analysis": true
  }
}

Configuration options:

•output_dir - Where to save spec documents
•use_builtin - Use built-in templates (true) or custom
•check_similar_projects - Query GitHub for similar implementations
•query_latest_docs - Get latest SUI tool documentation
•max_questions - Maximum questions to ask (prevents over-questioning)
•generate_mermaid - Generate Mermaid diagrams
•include_security_analysis - Include security threat model

Integration

Called By

•sui-full-stack (Phase 1: Architecture planning)

Calls

•sui-docs-query - Query latest SUI tool documentation and GitHub examples

Next Step

After architecture complete, suggest:

typescript

console.log("✅ Architecture and specification complete!")
console.log("Next: Ready to start development with sui-developer?")

Best Practices

Question Design

Good questions:

•"What types of listings do you want?" (specific, actionable)
•"How should royalties work?" (clear options)

Avoid:

•"Tell me everything about your project" (too broad)
•"Do you want features?" (vague)

Progressive Disclosure

•Start broad (project type)
•Narrow down (specific features)
•Deep dive (implementation details)

Validation Points

After each section, check understanding:

•"Does this match your vision?"
•"Need to adjust anything?"

Don't proceed until user confirms.

Common Mistakes

❌ Asking too many questions at once

•Problem: User overwhelmed, provides vague answers
•Fix: Ask ONE question at a time, wait for answer before proceeding

❌ Not validating each section before proceeding

•Problem: Architecture doesn't match user's vision, wasted rework
•Fix: After each section (Overview, Modules, etc.), ask "Does this look good?"

❌ Skipping ecosystem tool integration suggestions

•Problem: User reinvents features already available (Walrus, Kiosk, zkLogin)
•Fix: Always query and suggest relevant SUI tools during Phase 4

❌ Generic template without customization

•Problem: Spec doesn't reflect project's unique requirements
•Fix: Use template as starting point, customize based on Q&A responses

❌ Missing security considerations section

•Problem: Security vulnerabilities discovered late in development
•Fix: Always include threat model and security analysis in spec

❌ Not checking similar projects on GitHub

•Problem: Missed proven patterns, reinventing the wheel
•Fix: Query GitHub for similar implementations, reference best practices

❌ Proceeding without clear project type

•Problem: Wrong template selected, misaligned architecture
•Fix: Phase 1 must complete successfully before Phase 2 template selection

SUI Architect

Overview

Quick Start

SUI v1.65 Architecture Considerations (Protocol 110)

Core Workflow

Phase 1: Project Type Identification

Phase 2: Template Selection

Phase 3: Requirements Exploration

Phase 4: Ecosystem Tool Integration

Phase 5: Best Practice References

Phase 6: Architecture Design Presentation

Phase 7: Specification Document Generation

Output Files

Configuration

Integration

Called By

Calls

Next Step

Best Practices

Question Design

Progressive Disclosure

Validation Points

Common Mistakes

See Also