| 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 sessions must understand.
Read references/architecture-policy.md when deciding placement or documenting an ADR.
Anti-patterns
- Forced FSD/VSA rewrite of coherent existing architecture.
- Pure Layered architecture for new backends in 2026 (use VSA+Hexagonal+Modular).
- Use deprecated FSD
processes layer.
- Cross-slice internals imports instead of public APIs.
- Generic pass-through service/repository layers without abstraction value.
- Skip ADR for architecture decisions with long-term consequences.
