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 guide connects code ownership with the decisions you make across a full-stack application: how reads and mutations run, where access checks belong, and how server and browser caches stay current. Worked examples follow an orders feature through those decisions.
src/
app/ # Next.js routes and page composition
features/ # Business capabilities across server and client
platform/ # Database connections and external integrations
shared/ # Code with generic behavior across features
An orders feature owns its UI, schemas, business rules, reads, and mutations. Its public server operations enforce access and return the data callers may receive. Pages, Server Actions, and Route Handlers use those operations through the boundary each caller needs.
Apply the ownership and dependency rules from the first feature. Add abstractions such as repositories when persistence needs to be shared or substituted. When a cancellation rule changes, you should be able to open features/orders, find the use case, and follow it to the stored order.
Follow the guides in order, or start with the decision you're working on:
| Guide | What it helps you decide |
|---|---|
| Background & Motivation | Which recurring architecture decisions need a shared default before implementations drift. |
| Concepts | How feature ownership, public interfaces, and dependency direction shape the application. |
| Folder Structure | Where files belong, what callers may import, and when to introduce another module. |
| Data Fetching & Mutation | How to choose consistent data paths and when TanStack Query or oRPC fits that strategy. |
| Protected Resources | Where to verify sessions, enforce resource access, and limit the data returned to callers. |
| Caching | How Next.js caches interact, where cache policy belongs, and what to invalidate after a write. |
The three runnable applications demonstrate native Next.js, React Query with a separate HTTP backend, and React Query with oRPC. Each has its own PostgreSQL setup, seeded login accounts, and tests.
The RFAStack skill guides planning, implementation, and refactoring in your Next.js application.
Run this command from your application to install it through the skills CLI:
bunx skills add ishk-sftckz/RFAStack --skill rfastackUse npx skills in place of bunx skills if you use npm. To make the skill available across your projects, add --global. To select an agent directly, add --agent codex, --agent claude-code, or another supported agent name. For example:
bunx skills add ishk-sftckz/RFAStack --skill rfastack --global --agent codexCorrections and clearer examples are welcome. For a substantial architectural or editorial change, open an issue describing the failure mode, your proposed change, and its tradeoffs. Read CONTRIBUTING.md before opening a pull request.
Site source code is licensed under the MIT License. Original writing, documentation examples, diagrams, and visual assets are licensed under Creative Commons Attribution 4.0 International, with attribution to RFAStack by Ishk. See LICENSE.md for the boundaries when reusing material.
