Dima's 5-Rule Front-End Architecture Evaluator

Last updated: 7 June 2026

Evaluate any front-end architecture (or choose between FSD, Layered, and Vertical Slices) using five concrete criteria so you select the right structure for your project's size and stage.

// TL;DR

Dima's 5-Rule Front-End Architecture Evaluator is a framework for choosing or auditing front-end architectures using five concrete criteria: High Cohesion, Low Coupling, Discoverability, Mental Model Match, and Incremental Adoption. Use it when starting a new front-end project, auditing a painful codebase, or deciding between Feature Sliced Design, Layered Architecture, and Vertical Slices. It includes a Cohesion-Coupling matrix, a classification problem test, and project-size heuristics to match the right architecture to your team size, project stage, and domain complexity.

Framework

// When should you use Dima's 5-Rule Front-End Architecture Evaluator?

Use this skill whenever you are starting a new front-end project and need to pick an architecture, auditing an existing codebase that has become painful to work with, or debating whether Feature Sliced Design is the right fit for your team and project scale.

// What information do you need before evaluating a front-end architecture?

Project descriptionrequired
What the application does, its domain, and its rough feature count.
Team size and maturityrequired
Number of developers and their familiarity with architecture patterns.
Project stagerequired
Greenfield, early growth, or mature/large — affects incremental adoption scoring.
Architecture under evaluation (optional)
If auditing an existing architecture, name it. If choosing fresh, leave blank.
Known pain points (optional)
Current problems: e.g. merge conflicts, hard onboarding, unclear file placement.

// What are the five rules for evaluating front-end architecture?

High Cohesion

How many files do you need to open to change one feature, and how close are those files to each other? All code related to one business feature should be concentrated in one place. If it is scattered across many folders, cohesion is low — and that is what you want to avoid.

Low Coupling

When you change one module, does it affect other modules? Low coupling means you can change one module without breaking others. High coupling means one change can break modules you did not expect, making the architecture fragile.

Discoverability

Can a developer find the code they need to change quickly without spending too much time searching? Good discoverability means opening the project and knowing where to go fast enough.

Mental Model Match

Do business features map directly to folders in the codebase, or do developers need to translate between business concepts and architectural categories before they can find or write code? The folder structure should tell you what the application does — this is called Screaming Architecture.

Incremental Adoption

Can you start with a simple structure and add more rules as the project grows, or do you need to set up the full structure from day one even if the project is too small? Because requirements change and projects might not survive, architecture must be able to start small.

// How do you apply the 5-Rule Architecture Evaluator step by step?

1
Characterise the project
Establish project stage (greenfield / early growth / mature), team size, domain complexity, and any known pain points. This context drives all scoring and the final recommendation.
2
Score the architecture (or candidate architectures) against the Five Rules
For each of the five rules — High Cohesion, Low Coupling, Discoverability, Mental Model Match, Incremental Adoption — assign a rating: Good / Natural / Low / Poor. Use the definitions in the Principles section as the rubric. Do not skip a rule; every rule matters.
3
Identify the cohesion level (slice vs. feature)
Distinguish between slice-level cohesion (code within one slice is well-organised) and feature-level cohesion (all code for one business feature lives together across the whole project). An architecture can have good slice-level cohesion but low feature-level cohesion — as FSD demonstrates. Call this out explicitly.
4
Map coupling sources
Identify where cross-module dependencies arise. Ask: Are cross-imports forbidden by the architecture? Is there a workaround (e.g. the @x notation in FSD)? Does the workaround make dependencies explicit or just tolerated? High coupling that is invisible is worse than high coupling that is visible.
5
Check for the Classification Problem
For any architecture with multiple named layers, test whether the same component could plausibly live in more than one layer. If two developers on the same team would place the same component in different layers, the architecture has a Classification Problem — which harms discoverability and causes inconsistent placement.
6
Test for Screaming Architecture alignment
Look at the top-level folder names. Ask: Do these folders tell you what the application does (cart, payment, user) or what pattern it uses (features, entities, widgets)? The former is high Mental Model Match; the latter is technically-driven structure.
7
Score Incremental Adoption by asking the adoption question
Ask: Can you start this architecture with two or three folders and expand later? Or does it require the full structure — all layers, all naming conventions, all import rules — from day one? If the latter, mark Incremental Adoption as Poor and flag this as a risk for early-stage projects.
8
Plot the architecture on the Cohesion-Coupling matrix
Use four quadrants: Bottom-right = High Cohesion + Low Coupling (ideal target). Top-right = God Object (tightly connected, one module does too much). Bottom-left = Destructive Decoupling (separated but no clear purpose). Top-left = Poorly Chosen Boundaries (dependent models, scattered related code). State explicitly which quadrant the architecture sits in and why.
9
Select or recommend the appropriate architecture pattern
Apply the project-size heuristic: Small projects → Layered Architecture (3 layers: components, services, API — plus pages and shared). Medium to large projects → Vertical Slices (features first, technical layers inside each slice, shared for reusable utilities). Only choose FSD if the team already knows it, the project is known to be large and long-lived, and the team accepts the classification overhead and full upfront structure cost.
10
Apply the Architecture Decision Loop for ongoing evolution
Architecture is not a one-time decision. After each release cycle, ask: Do we need more structure (developers stepping on each other's toes, unexpected side effects) or less (features removed, scope reduced)? Change architecture based on feedback from the system, not from prediction alone.

// What does the 5-Rule Architecture Evaluator look like in practice?

A two-person team starting a SaaS dashboard app with five features planned, no existing architecture.

Score Incremental Adoption first — this is greenfield and small. FSD fails here (full structure from day one). Start with Layered Architecture: a components folder for UI, a services folder for business logic, an API folder for data fetching, plus pages and shared. As the team grows and features multiply, migrate toward Vertical Slices by regrouping code into feature folders (e.g. billing, user-settings, reports) with technical sub-folders inside each.

A ten-developer team on a mature e-commerce platform experiencing frequent merge conflicts and slow onboarding.

Pain points signal a cohesion and coupling problem. Score the current architecture: if files for one business feature (e.g. the add-to-cart flow) are scattered across multiple folders, feature-level cohesion is low. Recommend Vertical Slices — one folder per business domain (cart, checkout, product, user), each containing its own UI, logic, and API sub-folders. This raises Mental Model Match (screaming architecture), improves discoverability, and reduces onboarding time. Enforce cross-feature coupling discipline through code review rather than hard structural rules.

A team already using FSD asks whether to keep it or migrate.

Run the Five Rules audit. Confirm: slice-level cohesion is good, but feature-level cohesion is low (check how many layers a developer touches to fix one button). Check for Classification Problems — ask team members independently where they would place a shared search bar; disagreement confirms the problem. Check the shared layer for business logic creep (add-to-cart style components that snuck in). If the project is large and the team is fluent in FSD vocabulary, the documentation and shared vocabulary benefits may outweigh the costs — keep FSD but enforce @x notation for all cross-slice dependencies to make coupling explicit. If the project is small or the team is struggling with placement decisions, migrate to Vertical Slices incrementally by collapsing layers into feature folders.

// What mistakes should you avoid when evaluating front-end architecture?

Confusing slice-level cohesion (good in FSD) with feature-level cohesion (low in FSD) — they are different things and both matter.
Treating the shared layer as a dumping ground for any code that doesn't fit elsewhere — shared becomes huge and violates its own rule of containing no business logic.
Using the @x notation as a solution to coupling rather than recognising it as a visibility aid only — cross-slice coupling still increases architectural fragility even when made explicit.
Applying FSD (or any full architecture) to a small or early-stage project before requirements are stable — this locks you into structure you may need to discard.
Letting the Classification Problem go unresolved — if developers disagree about which layer a component belongs in, discoverability suffers and placement becomes inconsistent across the codebase.
Mistaking a technically-driven folder structure (features, entities, widgets) for a business-driven one (cart, payment, user) — only the latter achieves Screaming Architecture and high Mental Model Match.
Treating architecture as a one-time decision — architecture must be revisited each time the product changes significantly, using the Architecture Decision Loop.
Ignoring the DRY violation risk when duplicating components per slice to avoid cross-imports — if shared logic changes (e.g. adding a loading state), every duplicate must be updated manually.

// What key terms do you need to understand for front-end architecture evaluation?

Layers: The top-level folders in an FSD project, each with a distinct technical responsibility: app, pages, widgets, features, entities, shared. Lower layers cannot import from higher layers.
Slices: Folders within each layer organised by business domain (e.g. cart, authentication, search inside the features layer). One slice per business concept per layer.
Segments: Sub-folders within each slice organised by technical role: UI for components, model for business logic, API for data fetching, lib for utilities.
Public API: The index.js file at the root of each slice that defines what other parts of the app may import. Internal files must not be imported directly; the slice works as a black box.
@x notation: An official FSD workaround for cross-slice dependencies. A special @x folder inside a slice re-exports code intended for another slice, making the cross-import visible and explicit without eliminating the coupling.
High Cohesion: All code related to one feature or business concept is concentrated in one place, minimising how many files a developer must open and hold in mind to make one change.
Low Coupling: Changing one module does not affect other modules. Non-explicit dependencies (when a module depends on another unexpectedly) are a symptom of high coupling.
Discoverability: The ease with which a developer can locate the code responsible for a given behaviour without extensive searching or tribal knowledge.
Mental Model Match: The degree to which the folder structure reflects how the team thinks about the product. High match means business features map directly to folders with no translation required.
Incremental Adoption: The ability to start a project with minimal structure and add architectural rules only as pain points emerge, rather than requiring the full structure from day one.
Screaming Architecture: A folder structure whose top-level names communicate what the application does (cart, payment, user) rather than what pattern or technology it uses. Named after the idea that the structure should 'scream' the app's purpose.
Classification Problem: The situation where the same component could legitimately belong in more than one architectural layer, causing disagreement between developers and inconsistent placement across the codebase.
Vertical Slices: An architecture where the primary division is by business feature (e.g. cart, checkout), with technical sub-folders (UI, logic, API) inside each feature folder. The inverse of FSD's layered-first approach.
Layered Architecture: An architecture organised by technical responsibility with typically three layers for web: components (UI), services (business logic), and API (data access), plus pages and shared. Simpler than FSD and supports incremental adoption.
Architecture Decision Loop: The ongoing cycle of: build → receive feedback from the system (merge conflicts, unexpected side effects, onboarding difficulty) → decide whether to add or reduce structure → update architecture. Architecture is never a one-time decision.
Cohesion-Coupling Matrix: A four-quadrant diagnostic tool: ideal is High Cohesion + Low Coupling (bottom-right); failure modes are God Object (top-right), Destructive Decoupling (bottom-left), and Poorly Chosen Boundaries (top-left).
Feature-level cohesion: Whether all files for one complete business feature (across all technical concerns) live close together. Distinct from slice-level cohesion. FSD has good slice-level cohesion but low feature-level cohesion.
Slice-level cohesion: Whether code within a single FSD slice is well-organised internally. FSD achieves this but it is insufficient alone if related slices live in separate layers.

// FREQUENTLY ASKED QUESTIONS

What is Dima's 5-Rule Front-End Architecture Evaluator?

It is a framework that scores any front-end architecture against five criteria — High Cohesion, Low Coupling, Discoverability, Mental Model Match, and Incremental Adoption — to help you choose or audit a project structure. It provides a structured workflow including a Cohesion-Coupling matrix, a Classification Problem test, and project-size heuristics for recommending Layered Architecture, Vertical Slices, or Feature Sliced Design.

What are the five rules for evaluating front-end architecture?

The five rules are: (1) High Cohesion — all code for one feature lives together; (2) Low Coupling — changing one module doesn't break others; (3) Discoverability — developers find relevant code quickly; (4) Mental Model Match — folders reflect business concepts, not technical categories; (5) Incremental Adoption — you can start simple and add structure as the project grows.

How do I evaluate my current front-end architecture?

Score your architecture against each of the five rules (High Cohesion, Low Coupling, Discoverability, Mental Model Match, Incremental Adoption) using ratings like Good, Natural, Low, or Poor. Then identify whether cohesion is at the slice or feature level, map cross-module coupling sources, test for the Classification Problem, check for Screaming Architecture alignment, and plot the result on the Cohesion-Coupling matrix.

How do I choose between Feature Sliced Design, Vertical Slices, and Layered Architecture?

Use the project-size heuristic: small projects benefit from Layered Architecture (components, services, API, pages, shared). Medium to large projects should use Vertical Slices with feature-first folders. Choose FSD only if your team already knows it, the project is confirmed large and long-lived, and the team accepts the upfront structure cost and classification overhead.

How does Dima's evaluator compare to just picking Feature Sliced Design by default?

FSD is one specific architecture with trade-offs the evaluator exposes. FSD scores well on slice-level cohesion but poorly on feature-level cohesion, and it requires full structure from day one, making Incremental Adoption poor. The evaluator surfaces these trade-offs objectively so you pick based on evidence, not popularity. For small or early-stage projects, the evaluator typically steers you toward simpler alternatives.

When should I use the 5-Rule Architecture Evaluator?

Use it when starting a new front-end project and need to pick a structure, when auditing an existing codebase that has become painful (merge conflicts, slow onboarding, unclear file placement), or when debating whether Feature Sliced Design is the right fit for your team and project scale. It is also useful during periodic architecture reviews as part of the Architecture Decision Loop.

What is the Classification Problem in front-end architecture?

The Classification Problem occurs when the same component could legitimately belong in more than one architectural layer — for example, a search bar that could be a widget, a feature, or an entity in FSD. If two developers on the same team would place it differently, discoverability suffers and file placement becomes inconsistent across the codebase. Test for it by asking team members independently where they'd put a component.

What results can I expect after applying the 5-Rule evaluator?

You get a clear, evidence-based recommendation for which architecture pattern fits your project, a scored assessment of your current structure's strengths and weaknesses, identification of specific problems like the Classification Problem or shared-layer bloat, and a Cohesion-Coupling matrix placement showing whether you're in the ideal quadrant or a failure mode. This replaces gut-feel architecture decisions with repeatable analysis.

What is Screaming Architecture and why does it matter for front-end projects?

Screaming Architecture means your top-level folder names communicate what the application does — like cart, payment, user — rather than what technical pattern it uses — like features, entities, widgets. It matters because it maximizes Mental Model Match, making the codebase immediately understandable to new developers and ensuring business concepts map directly to the file structure without translation.

What is the Cohesion-Coupling matrix in front-end architecture?

It is a four-quadrant diagnostic tool. The ideal quadrant (bottom-right) is High Cohesion plus Low Coupling. The failure modes are: God Object (top-right, tightly connected modules doing too much), Destructive Decoupling (bottom-left, separated code with no clear purpose), and Poorly Chosen Boundaries (top-left, dependent models with scattered related code). Plotting your architecture here reveals which structural problem to fix first.

// GET THIS SKILL — FREE