---
name: ui-five-layer-architecture
description: Define, review, and refactor UI modules using a strict five-layer architecture (UseCase, RawData, Controller, Context, View). Use when creating cross-project UI architecture standards, designing new UI modules, reviewing layer boundaries and event flow, converting ad-hoc UI code into layered structure, or validating UI test strategy for business-driven interfaces.
---

# UI Five-Layer Architecture

## Quick Start

1. Read `./references/ui-five-layer-standard.md`.
2. Classify the UI as `standard-five-layer` or `lightweight`.
3. Apply boundary rules before editing code or writing design output.
4. Use the checklists in this file to drive design, review, or refactor tasks.

## Workflow

### 1. Scope the task

Decide which mode the user needs:

- architecture-spec mode: create or revise a UI architecture standard
- design mode: design one or more UI modules before coding
- implementation mode: implement or refactor code to match the standard
- review mode: audit existing code for boundary or dependency violations

### 2. Choose module level

Use `standard-five-layer` when UI owns business state transitions, validations, or branching behavior.

Use `lightweight` when UI only handles display/navigation and has no independent business rules.

### 3. Enforce non-negotiable boundaries

Apply these constraints in every mode:

- keep `UseCase` business-only and return only `RawData/Result`
- build `Context` only inside `Controller`
- keep `View` presentation-only and event-emitting only
- keep `View` out of global business event subscriptions
- route external UI open/close/refresh through `Controller`

### 4. Apply communication and dependency checks

Validate:

- dependency direction is valid for all touched files
- UI-specific events stay UI-local in meaning
- `Controller` filters sender and instance scope when needed
- no `RawData` field uses `*Context` types

### 5. Produce mode-specific output

- architecture-spec mode:
  - output the final standard text
  - include strict rules, permitted exceptions, and checklists
- design mode:
  - output layer map and flow diagram for each UI module
  - include type list and event list
- implementation mode:
  - implement code changes matching the standard
  - update tests if `UseCase` behavior changes
- review mode:
  - report findings first, ordered by severity
  - include concrete file and line references

## Architecture Checklist

Use this list before closing any task:

1. Classify each UI module correctly: `standard-five-layer` or `lightweight`.
2. Ensure `UseCase` does not construct `Context` or touch view concerns.
3. Ensure `RawData` does not include `*Context` or presentation types.
4. Ensure `Controller` owns all `RawData/Result -> Context` transformation.
5. Ensure `View` only consumes `Context` and emits UI-local events.
6. Ensure external open/close/update operations enter through `Controller`.
7. Ensure event ownership and sender filtering are explicit.
8. Ensure test approach matches policy in the reference file.

## References

Read `./references/ui-five-layer-standard.md` for the full specification.