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

```bash
# 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 mainnet v1.80.1 / P137)

When designing architectures, account for these recent platform changes:

- **Protocol Version 127** (shipped testnet v1.74.0; mainnet now v1.80.1 / P137) — 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).
- **Protocol Versions 131-133** (mainnet v1.77.2, live since 2026-08-13) — P131 `framework_tx_context_mut_restrictions` restricts system-package functions only (user packages unaffected); new `ForwardingAddressRegistry` system object (`0x2::forwarding_address`, ID `0xfa`) is **devnet-gated**, not yet on mainnet. Move-authoring depth → see sui-developer's Protocol Updates section.
- **Protocol Versions 134-135** (mainnet v1.78.1 / P135, live since 2026-08-29) — `defer_unpaid_amplification` disabled on all chains; consensus block limits raised (`consensus_max_transactions_in_block_bytes` = 288 KiB, `consensus_max_num_transactions_in_block` = 128); new framework function `sui::package::original_package_id(&UpgradeCap): ID` (native-backed) — see sui-deployer. `ForwardingAddressRegistry` remains devnet-only.
- **Data Access:** gRPC (GA, backend/low-latency/streaming default), GraphQL RPC (GA, frontend/indexer/complex queries), JSON-RPC (**shut off on public fullnodes** since 2026-07-31, Quorum Driver disabled)
- **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/](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](references/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

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](references/reference.md) - Template library, security considerations, advanced configuration
- [examples.md](references/examples.md) - Complete Q&A walkthrough, full specification example
- [templates/](templates/) - All project templates (NFT, DeFi, GameFi, DAO)
- [../sui-developer/references/object-model.md](../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!**

• SKILL.md 11 KB
• references/examples.md 19 KB
• references/reference.md 14 KB
• templates/dao.json 1 KB
• templates/defi-amm.json 1 KB
• templates/gamefi.json 1 KB
• templates/nft-marketplace.json 1 KB