aaronbassett/compact-reviewer:design-architecture

Design & Architecture Skill

Evaluate contract structure, design patterns, and architectural quality.

When to Use

This skill activates for queries about:

• Contract architecture and structure
• Design patterns in Compact
• Modularity and organization
• API design
• Code organization

Trigger words: architecture, design pattern, structure, modularity, organization, layout, API design

Quick Reference

Architecture Checklist

| Aspect | Check | Severity | |--------|-------|----------| | Separation of concerns | Each circuit has one responsibility | 🟡 Medium | | State encapsulation | Ledger access is controlled | 🟠 High | | Clear interfaces | Export circuits have clear purposes | 🟡 Medium | | Naming conventions | Circuits/ledgers clearly named | 🟢 Low | | Documentation | Public interfaces documented | 🟢 Low |

Good Architecture Patterns

// ✅ Single responsibility circuits
export circuit deposit(amount: Uint<64>): [] { }
export circuit withdraw(amount: Uint<64>): [] { }
export circuit get_balance(): Uint<64> { }

// ✅ Helper circuits for reusable logic
circuit verify_owner(): [] {
    const caller = get_caller_secret();
    assert hash(caller) == owner_hash.read();
}

// ✅ Clear state organization
ledger balances: Map<Bytes<32>, Uint<64>>;
ledger config: Cell<Config>;
ledger admin: Cell<Bytes<32>>;

Anti-Patterns

// ❌ God circuit - does too much
export circuit do_everything(
    action: Uint<8>,
    arg1: Field,
    arg2: Field,
    arg3: Field
): Field {
    if action == 0 { /* deposit */ }
    if action == 1 { /* withdraw */ }
    if action == 2 { /* transfer */ }
    // ...
}

// ❌ Unclear naming
export circuit proc(x: Field): Field { }
ledger d: Map<Bytes<32>, Uint<64>>;

Review Process

1. Structure Analysis

Evaluate overall organization:

1. Count exported circuits - too many (>10) suggests splitting
2. Check circuit sizes - >50 lines may be too complex
3. Verify helper circuits are used appropriately
4. Confirm ledger declarations are grouped logically

2. Pattern Recognition

Identify common patterns:

| Pattern | Indicators | Quality | |---------|------------|---------| | Owner pattern | owner_hash, verify_owner() | ✅ Good | | Access control | Role-based checks | ✅ Good | | Upgrade pattern | implementation ledger | ⚠️ Complex | | Multi-sig | Multiple signatures required | ✅ Good | | State machine | Enum-based state | ✅ Good |

3. Interface Design

Check public API:

1. Are circuit names descriptive?
2. Are parameters minimal and clear?
3. Is return type appropriate?
4. Are related operations grouped?

4. Modularity Assessment

Evaluate separation:

1. Can logic be tested independently?
2. Are concerns separated?
3. Is state access controlled?
4. Are dependencies explicit?

References

• Architecture Patterns - Good patterns
• Anti-Patterns - Patterns to avoid

Related Skills

• code-quality - Code organization
• maintainability - Long-term structure