home / skills / hoangnguyen0403 / agent-skills-standard / architecture

architecture skill

This skill enforces iOS MVVM, Coordinator, and VIPER architecture guidelines to improve modularity, testability, and clean separation of concerns.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill architecture

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.8 KB

---
name: iOS Architecture
description: Standards for MVVM, Coordinators, and Clean Architecture (VIP/VIPER).
metadata:
  labels: [ios, architecture, mvvm, coordinator, vips]
  triggers:
    files:
      [
        '**/*ViewModel.swift',
        '**/*Coordinator.swift',
        '**/*ViewController.swift',
      ]
    keywords: [MVVM, Coordinator, ViewState, Output, Input]
---

# iOS Architecture Standards

## **Priority: P0**

## Implementation Guidelines

### MVVM (Model-View-ViewModel)

- **ViewModel Responsibility**: Handle business logic, formatting, and state. No UIKit imports (except for platform types like `UIImage` if strictly necessary).
- **ViewState**: Use a single state object or discrete `@Published` properties for UI updates.
- **Inputs/Outputs**: Define explicit protocols or nested types for inputs (events from View) and outputs (state for View).

### Coordinator Pattern

- **Navigation Logic**: Decouple ViewControllers from navigation logic. The Coordinator handles instantiation and push/present.
- **Dependency Injection**: Pass dependencies (Services, Repositories) through the Coordinator into the ViewModels.
- **Child Coordinators**: Maintain a hierarchy; remove child coordinators when their flow is finished.

### Clean Architecture (VIP/VIPER)

- **VIP (Clean Swift)**: Use Interactor for logic, Presenter for UI formatting, and ViewController for display.
- **Unidirectional Flow**: Data flows: View -> Interactor -> Presenter -> View.

## Anti-Patterns

- **Massive View Controller**: `**No Logic in VC**: Move business logic to ViewModel/Interactor.`
- **Violating Encapsulation**: `**No Public ViewModel State**: Keep state private(set) or using publishers.`
- **Direct Navigation**: `**No self.navigationController?.push(...)**: Use a Coordinator.`

## References

- [MVVM-C & VIP Implementation](references/implementation.md)

Overview

This skill documents iOS architecture standards focused on MVVM, Coordinators, and Clean Architecture (VIP/VIPER). It defines responsibilities, anti-patterns, and wiring patterns to keep code modular, testable, and maintainable. The goal is to guide developers and agents to produce consistent, production-ready iOS code.

How this skill works

The skill inspects code and design decisions against a set of rules: ViewModels must contain business logic and state, Coordinators must own navigation, and VIP components must keep a unidirectional flow. It enforces separation of concerns by checking for UIKit usage inside ViewModels, direct navigation calls in view controllers, and public mutable state leaking from presentation layers. The rules also recommend dependency injection through coordinators and removing child coordinators when flows end.

When to use it

When designing new feature flows that require testable UI logic and clear navigation.
When refactoring a Massive ViewController into smaller, focused components.
When adopting a team-wide standard for consistency across iOS apps.
When introducing VIP/VIPER for complex business rules and strict separation.
When validating pull requests for architecture regressions or anti-patterns.

Best practices

Keep ViewControllers thin: move formatting and business logic to ViewModels or Interactors.
Define explicit input/output protocols for ViewModels to clarify events and state.
Avoid UIKit imports in ViewModels; allow platform types only when strictly necessary.
Use Coordinators to instantiate view controllers and inject dependencies via initializers.
Maintain child coordinator lifecycle: add on start, remove on completion to avoid leaks.
Prefer private(set) or publishers for ViewModel state to prevent external mutation.

Example use cases

Implementing a login flow: Coordinator creates ViewModel, injects auth service, and handles transitions.
Refactoring a screen: extract business logic into an Interactor and presentation into a Presenter.
Code review automation: flag direct navigation calls or public mutable view model state.
New feature scaffold: generate ViewController, ViewModel, and Coordinator templates that follow standards.
Cross-team onboarding: provide a checklist for MVVM vs VIP adoption and expected boundaries.

FAQ

When should I choose MVVM over VIP/VIPER?

Use MVVM for most screens where view logic and state are moderate; pick VIP/VIPER when you need strict separation, complex business rules, or multiple presenters and interactors for testability.

Can a ViewModel reference UIKit types like UIImage?

Avoid UIKit in ViewModels. Allow platform types only when strictly necessary and document why; prefer presenters/formatters to convert domain data into UI-safe types.