sui-architect

name

sui-architect

description

Use when planning SUI Move architecture, generating technical specs, or designing object/module structure before writing code. Triggers on "design", "architect", "plan the contracts", "object model", "module structure", "how should I structure", or any SUI system design task. For new projects from scratch, use sui-full-stack (which calls this skill at Phase 1). For ecosystem tool/stack selection (Walrus vs IPFS, zkLogin vs Passkey), use sui-tools-guide.

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

# Start architecture planning
sui-architect

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

SUI Protocol 127 Architecture Considerations (shipped testnet v1.74.0; now v1.74.1 / P128 on both testnet and mainnet)

When designing architectures, account for these recent platform changes:

• Protocol Version 127 (shipped testnet v1.74.0; both networks now v1.74.1 / P128) — enables always_advance_dkg_to_resolution (fixes P126), Ristretto255 group ops + Bulletproofs on testnet, timestamp-based epoch close on mainnet, gRPC SimulateTransaction accepts gas_price=0 (gasless tier).
• Data Access: gRPC (GA, backend/low-latency/streaming default), GraphQL RPC (GA, frontend/indexer/complex queries), JSON-RPC (deprecated, Quorum Driver disabled, permanent deactivation 2026-07-31)
• Address Balances (Mainnet, P125): Native address-held balances for supported coin types — PTBs can debit/credit them directly without manual coin select/split/merge. Additive, not a replacement: flows that take Coin<T> still need coin objects.
• Gasless Stablecoin Transfers (Mainnet, P125, rolling out): Accumulator + coin reservations let users move USDC etc. without holding SUI for gas.
• Display V2 (Activated): Display Registry (0xd) live on all networks — prioritized over legacy Display v1. Plan new projects around Display V2.
• Balance API Split: coinBalance (fungible coins only) and addressBalance (all balance types)
• Other platform/runtime notes (P126 + earlier rollouts): entry-fn signature check disabled & non-public entry fns can't take hot-potato-entangled args; TxContext flexible positioning (no longer must be last param); poseidon_bn254 on all networks; Adaptive Concurrency (Processor::FANOUT removed → ConcurrencyConfig); DeepBook explicit Move.toml dep (v1.47+); Address Aliases live on mainnet. Move-authoring depth → see sui-developer's Protocol 127 section.
• SDK Naming: @mysten/sui (not @mysten/sui.js), Transaction (not TransactionBlock)

Core Workflow

Phase 1: Project Type Identification

Ask user about their project type:

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)
• Data access pattern (gRPC for current state, GraphQL for frontend queries, custom indexer for historical analytics/aggregation — see sui-indexer)
• 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
• Custom data pipeline / historical analytics → sui-indexer

For the latest integration patterns (e.g. transfer-policy implementation), use the sui-docs-query skill (Context7 MCP).

Phase 5: Best Practice References

For reference implementations and example projects, use the sui-docs-query skill (Context7 MCP) — e.g. "NFT marketplace example Kiosk".

Phase 6: Architecture Design Presentation

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

1. System Overview
2. Module Architecture
3. Data Structures
4. Core Functions
5. Permission System (Capabilities)
6. Event System
7. Error Handling
8. Security Considerations
9. Tool Integration Plan
10. Data Layer (gRPC vs GraphQL vs Custom Indexer — see decision table in sui-indexer)
11. Testing Strategy
12. Deployment Plan
13. 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:

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:

{
  "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:

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

1. Start broad (project type)
2. Narrow down (specific features)
3. 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

See Also

• reference.md - Template library, security considerations, advanced configuration
• examples.md - Complete Q&A walkthrough, full specification example
• templates/ - All project templates (NFT, DeFi, GameFi, DAO)
• ../sui-developer/references/object-model.md — Read when choosing object ownership for parallel execution (owned/derived parallelize; shared by & parallelizes, by &mut/value serializes) or derived vs dynamic-field storage

---

Transform fuzzy ideas into crystal-clear, implementable architectures!