Skip to content

REACT FULLSTACK ARCHITECTURE / NEXT.JS

RFAStack

An Opinionated React Fullstack Architecture for Next.js Applications

A Next.js application rarely becomes hard to maintain overnight. It happens one reasonable shortcut at a time, until nobody is sure where business logic belongs or what a small change might break. RFAStack gives you an opinionated architecture to follow before the codebase reaches that point.

THE GAP / APPLICATION DECISIONS

You can know the Next.js APIs and still be unsure where your code belongs

The documentation can show you how a Server Component, Server Action, or Route Handler works. Your application still needs rules for when to use each one, where business logic lives, and what several callers should share.

01 / THE FIRST FEATURE

A page reads from the database. A mutation stays in a Server Action. A helper goes into utils. Each choice works for the feature in front of you.

02 / THE PATTERNS DRIFT

Another page calls an internal endpoint for the same kind of read. Another mutation keeps its checks somewhere else. Each implementation works, but the next developer has no clear pattern to follow.

03 / THE SHARED RULE

Keep business rules with the feature that owns them. Pages, Server Actions, and Route Handlers can call the same operation through the boundary they need.

THE COST / UNCERTAINTY

A small change should not begin with a repository-wide search

You should be able to find the feature, see where its rules live, and follow each read or mutation to the data it touches. When two paths do the same work and nobody can explain why, every change starts with investigation. That uncertainty slows reviews, encourages repeated mistakes, and becomes technical debt.

THE APPROACH / DEFAULTS WITH BOUNDARIES

Give every business rule an owner and every data path a reason

The folder tree, server code, and the way data moves should support the same decisions. Start with the direct path, then add structure when the application gives you a reason.

  1. 01

    Start with the operation

    Decide what the code must do and who needs it before choosing a Server Action, Route Handler, or client-side library.

  2. 02

    Business rules belong to features

    Put the rule in one feature, then let pages, actions, and handlers call it instead of rewriting it.

  3. 03

    Reads and mutations should be traceable

    You should be able to follow the caller to the feature, then follow the feature to the database or outside service.

  4. 04

    Extra structure needs a requirement

    Keep the direct path until the browser, an external caller, or protected data requires another boundary.

ARCHITECTURE FOUNDATIONS / OWNERSHIP

The folder tree should show where product behavior belongs

A neat folder tree is easy to copy and easy to misuse. src/app contains Next.js entry points. src/features owns product behavior. src/platform handles databases and outside services. src/shared holds code with no product-specific rule. Copy the names without the ownership rules and you get four new junk drawers.

RFAStack architecture mapRequests enter through src/app and delegate to a feature in src/features. Feature code may call integrations in src/platform and generic primitives in src/shared.CALL FLOW · OWNERSHIP STAYS WITH BUSINESS CAPABILITIESNOT TO SCALEA / NEXT.JS BOUNDARYsrc/apppages · layouts · handlersF / BUSINESS CAPABILITIESsrc/featuresorders / billing / identity / reportingUI · model · queries · mutations · serverOWNS THE BEHAVIORP / INTEGRATIONSsrc/platformdatabase · email · telemetryS / GENERIC PRIMITIVESsrc/sharedUI · types · utilities
Text alternative: requests enter through src/app and delegate to feature-owned behavior in src/features. Features may call integrations in src/platform and generic primitives in src/shared.

READING PATH / RFASTACK

From code ownership to data flow

Follow the decisions that shape a Next.js application across features, framework boundaries, server code, and data sources.

  1. 01Background & MotivationWhy working Next.js applications become harder to change when each feature follows a different rule.
  2. 02Architecture FoundationsHow feature ownership, public interfaces, and dependency direction decide where code belongs.
  3. 03Data Fetching & MutationHow to choose a path for reads and mutations across server code, browser state, and external callers.
  4. 04Protected ResourcesProtect reads and mutations with session verification, resource access checks, and safe returned data.
  5. 05CachingUnderstand what each cache reuses, where feature cache policy belongs, and how writes reach the server and browser views.
  6. 06Runnable ExamplesRun a customer portal, a fulfillment dashboard, or a B2B ordering app and trace its requests through the source.

Code: MIT · Writing, diagrams, and visual assets: CC BY 4.0