How Should Tech Leads Evaluate and Evolve Front-End Architecture?
For Front-end tech leads and engineering managers · Based on Dima's 5-Rule Front-End Architecture Evaluator
// TL;DR
Tech leads need a repeatable, evidence-based process for evaluating front-end architecture — not opinion-driven debates. Dima's 5-Rule Evaluator provides five testable criteria (High Cohesion, Low Coupling, Discoverability, Mental Model Match, Incremental Adoption), a Cohesion-Coupling matrix for visual diagnosis, and a Classification Problem test that settles team disagreements about file placement. Use it to audit existing codebases, justify migration decisions to stakeholders, and build an Architecture Decision Loop into your team's release cycle.
How do you objectively audit a front-end codebase that's become painful?
Start by gathering data: project stage, team size, domain complexity, and documented pain points (merge conflicts, slow onboarding, unclear file placement). Then score the architecture against each of the five rules.
For cohesion, count how many files a developer opens to change one business feature. Distinguish between slice-level cohesion (internal organization within a module) and feature-level cohesion (whether all code for one feature lives together). An architecture like FSD can have good slice-level cohesion but poor feature-level cohesion — this distinction is critical.
For coupling, map cross-module dependencies. Ask: when one module changes, which other modules break? Are these dependencies explicit or hidden? Plot your findings on the Cohesion-Coupling matrix to identify which quadrant your architecture occupies.
How do you resolve team disagreements about where code should go?
Run the Classification Problem test. Ask three or more developers independently where they would place a specific component — such as a search bar that appears in multiple features. If they disagree on the layer or folder, you have an objective signal that your architectural categories are ambiguous.
The fix depends on severity. If disagreements are occasional, write explicit placement rules with real examples and enforce them through code review. If disagreements are frequent, the architecture itself may be too granular — consider simplifying from FSD's seven layers to Vertical Slices' feature-first structure, which has fewer ambiguous boundaries.
Document the classification rules your team agrees on and add them to your project's contributing guide. This is more effective than tribal knowledge.
How do you justify an architecture migration to non-technical stakeholders?
Use the five rules as a reporting framework. Show that the current architecture scores Low or Poor on specific criteria — for example, developers spending 30% of their time finding code (low Discoverability) or merge conflicts increasing 3x over the last quarter (high Coupling).
The Cohesion-Coupling matrix provides a visual that non-technical stakeholders can understand: "We're in the Poorly Chosen Boundaries quadrant — related code is scattered and changes cause unexpected breakage. Moving to Vertical Slices puts us in the ideal quadrant."
Frame the migration as incremental — one business domain at a time — to reduce perceived risk.
How do you build ongoing architecture review into your team's process?
Implement the Architecture Decision Loop. After each release cycle (or every two to three sprints), ask three questions: Are developers stepping on each other's toes? Are changes causing unexpected side effects? Is onboarding getting slower or faster?
If the answers indicate growing pain, add structure — migrate the most problematic area to a more structured pattern. If the project scope has shrunk, reduce structure to avoid over-engineering. Record each decision and the feedback that triggered it in an architecture decision record (ADR) for institutional memory.
Start your next architecture review by running the full 10-step workflow with your team's current pain points as input.
// FREQUENTLY ASKED QUESTIONS
How do I convince my team to change our front-end architecture?
Run the 5-Rule audit with the team, not in isolation. When developers see objective scores — especially a failing Classification Problem test where they disagree with each other on file placement — the need for change becomes self-evident. Frame the migration as incremental: one domain at a time, not a full rewrite.
How often should a tech lead review front-end architecture?
Do a lightweight check every two to three sprints using the Architecture Decision Loop — look for merge conflicts, unexpected side effects, and onboarding speed. Do a full 5-Rule audit quarterly or whenever the team hits a clear inflection point like doubling in size, launching a major feature area, or experiencing a spike in developer friction.
What's the best way to document architecture decisions for a front-end team?
Use Architecture Decision Records (ADRs) that capture the 5-Rule scores at the time of the decision, the pain points that triggered the review, the options considered, and the rationale for the choice. Include the Cohesion-Coupling matrix quadrant assessment. This creates institutional memory that survives team turnover.