Architecture principles
Cohesion, coupling, the direction of dependencies, the public interface, colocation.
Updated
What a frontend project's architecture is
Architecture = the rules by which you organize code: where each file lives, who can import whom and how the parts communicate. It isn't about the framework (React, Next), but about the structure of your code on top of it.
Why architecture matters
At 10 files any structure works. At 500, the structure decides whether you find the code in 5 seconds or 5 minutes, and whether a change breaks 1 place or 15.
5 principles behind any architecture
1. High cohesion — what changes together lives together. The component, the hook, the types and the query for "cart" — in the same place.
2. Low coupling — modules know as little as possible about each other. They communicate through small interfaces (props, exported functions), not internal details.
3. The direction of dependencies — dependencies flow in a single direction: from specific code (pages) toward generic code (utilities). Never the other way around. That's how you avoid circular imports.
views→features→entities→sharedThe other way around (shared importing from features) — forbidden.
4. A clear public interface — each module decides what it exposes. The rest is an internal detail that can change freely.
5. Colocation — keep things as close as possible to where they're used. Something becomes "shared" only when it's actually used in 2–3 places.
Signs the architecture isn't working
- "Where do I put this file?" — a daily question.
- A
utils/orcomponents/folder with 80 unrelated files. - You change a component and a page that "had nothing to do with it" breaks.
- Imports like
../../../../shared/x. - You delete a feature and pieces of it remain all over the project.
Practical rules, whatever the architecture
- Descriptive file names (
site-header.tsx, notindex.tsx× 40). - Business logic does not live in UI components — you extract it into pure (testable) functions.
- Data access (fetch, SQL) in a single layer, not scattered across components.
- Lint can enforce the import rules (e.g.
eslint-plugin-boundaries, Steiger for FSD).
Summary
- Architecture = where the code lives and who can import whom.
- High cohesion, low coupling, dependencies in a single direction.
- A clear public interface, colocation, business logic separated from the UI.