architecture-boundaries

name	architecture-boundaries
description	Архитектурные границы: FSD/VSA/Hexagonal, modules, public APIs, imports. Используй для: архитектура, слои, FSD, VSA, hexagonal, frontend, backend, размещение кода, границы модуля, публичный API. EN triggers: architecture boundaries, module layers, public API design, import discipline, where to place code, ADR worthy, layer policy.

Architecture Boundaries

Purpose

Keep systems easy to understand, change, and scale by using stable architecture boundaries and project-consistent placement.

Default Architecture (May 2026)

• Existing project architecture is the source of truth. Do not rewrite architecture just to satisfy a generic rule.
• New frontend, web UI, mobile UI, and desktop UI areas default to Feature-Sliced Design when the stack allows it.
• New backend areas default to Vertical Slice Architecture when the application is use-case, command, query, route, or handler oriented. Combine with Hexagonal (Ports & Adapters) for framework-agnostic durability and Modular Monolith as the organizational container for medium-scale systems.
• Important architecture or technology decisions require an ADR (MADR 4.0.0 format) or equivalent decision record.

Frontend And Client UI (FSD)

• Prefer FSD layers: app, pages, widgets, features, entities, shared.
• Treat the deprecated processes layer as forbidden by default; route its responsibilities into app/pages/widgets depending on scope.
• Imports should point only to lower layers, except app and shared rules and explicit project exceptions.
• Use public APIs for slices. Avoid deep imports into slice internals.
• Keep shared business-agnostic. Business concepts belong in entities, features, widgets, or pages.

Backend (VSA + Hexagonal + Modular Monolith)

• VSA: organize around use cases, commands, queries, routes, or handlers. Validation, handler logic, domain orchestration, persistence interaction, and response mapping must be easy to trace for one use case.
• Hexagonal (Ports & Adapters): isolate domain core from infrastructure (DB, HTTP, queues). Ports define contracts, adapters implement them. Survives framework churn.
• Modular Monolith: module boundaries form the outer container; vertical slices organize features within; ports/adapters protect the core.
• Minimize cross-slice coupling. Shared backend code must be stable, genuinely reusable, and not a dumping ground.
• Avoid generic service/repository layers when they only pass data through and add no useful abstraction.
• Cross-cutting concerns such as auth, logging, observability, transactions, and error mapping must be explicit and consistently placed.
• Pure layered architecture is acceptable only for MVPs or small projects where speed matters more than sustainability.

ADR Triggers

Create an ADR for:

• New architecture style or major boundary change.
• New framework, database, message broker, auth strategy, deployment model, or critical dependency.
• Intentional deviation from FSD/VSA defaults.
• Breaking public API or contract change.
• Long-lived tradeoff that future Claude Code sessions must understand.

Read ${CLAUDE_PLUGIN_ROOT}/references/architecture-policy.md when deciding placement or documenting an ADR.

Anti-patterns

• Forced FSD/VSA rewrite of coherent existing architecture.
• Pure Layered architecture для new backends в 2026 (use VSA+Hexagonal+Modular).
• Use deprecated FSD processes layer.
• Cross-slice internals imports вместо public APIs.
• Generic pass-through service/repository layers без abstraction value.
• Skip ADR для architecture decisions с long-term consequences.