Intent Over Implementation: React That Reads Like Your Product

Intent Over Implementation: React That Reads Like Your Product

We just restructured our React frontend to scream its purpose, not its tech stack.

feature centric vs tech jargon

Most apps group by technical concerns (commands, queries, consumers). It looks tidy, but navigating by “how” often hides the “why.” We shifted to a product/feature-first structure (aka Screaming Architecture) so the app advertises what it does at a glance.

Why this matters

• Strong coupling for related features, weak coupling for unrelated ones
• Higher cohesion and easier navigation
• Faster onboarding and PR reviews
• Clearer ownership and safer refactors

Before vs After

Before (tech-first)
src/
  components/
  services/
  commands/
  queries/
  events/
  utils/

After (feature-first)
src/
  features/
    product/
      components/
      hooks/
      api/
      types/
      tests/
    cart/
    checkout/
  shared/
    ui/
    hooks/
    api/
    utils/

How we made it stick

• Co-locate UI, hooks, tests, and API calls per feature
• Keep “shared/” small and intentional (thin primitives, not a dumping ground)
• Use clear boundaries and barrel files per feature
• Align routing, analytics, and ownership with features (not layers)

What improved

• Navigate by intent: “I’m changing checkout,” not “where do we keep queries?”
• Fewer cross-feature imports and regressions
• Cleaner diffs; smaller, reviewable PRs
• Feature teams ship independently

Credit where it’s due: Screaming Architecture encourages structure that communicates purpose. The directory should read like your product, not your framework.

Curious how you structure your React apps — feature slices, verticals, or something else?