REACT / NEXT.JS SCALABLE SYSTEM DESIGN RULES

These rules define mandatory architecture, data flow, and code organization for scalable React / Next.js applications using:

• Next.js (App Router or TanStack Start equivalent)
• TanStack Query
• TypeScript
• Feature-based architecture

These rules MUST be followed by:

• Developers
• AI code generators
• Code reviewers

🧱 ARCHITECTURE RULES

RULE: FEATURE-BASED STRUCTURE IS MANDATORY

All code MUST be organized by feature.

• Each domain MUST have its own isolated module
• Cross-feature coupling is FORBIDDEN

Allowed:

• features/auth
• features/rules
• features/profile

Forbidden:

• global components folder for business logic
• shared services containing feature logic

RULE: FEATURES MUST BE SELF-CONTAINED

Each feature MUST include:

• components
• hooks
• services
• queries
• types

A feature MUST NOT depend on another feature’s internal files.

RULE: SHARED LAYER IS STRICTLY LIMITED

The shared layer MAY contain ONLY:

• UI primitives
• generic hooks
• utilities
• API client

The shared layer MUST NOT contain:

• business logic
• feature-specific rules
• domain-specific APIs

🔁 DATA FLOW RULES

RULE: SERVER STATE MUST USE TANSTACK QUERY

All server data MUST be handled via TanStack Query.

Forbidden:

• fetch inside useEffect
• direct API calls in components

RULE: QUERY KEYS MUST BE STRUCTURED

Query keys MUST include parameters.

Allowed:

• ['rules', { page, filter }]
• ['profile', userId]

Forbidden:

• ['rules']
• ['data']

RULE: MUTATIONS MUST INVALIDATE QUERIES

Every mutation MUST define cache invalidation.

Example requirement:

• create → invalidate list
• update → invalidate detail + list

RULE: NO DUPLICATE DATA SOURCES

A single source of truth MUST exist per data entity.

Forbidden:

• storing API data in local state AND query cache
• syncing multiple stores manually

🌐 API LAYER RULES

RULE: API CALLS MUST BE ISOLATED

All API logic MUST exist inside:

• feature/services

Components MUST NEVER call APIs directly.

RULE: API FUNCTIONS MUST BE PURE

API functions MUST:

• return data only
• contain no UI logic
• contain no React hooks

RULE: CENTRALIZED API CLIENT IS REQUIRED

A single API client MUST handle:

• authentication headers
• error handling
• base URL

🧩 COMPONENT RULES

RULE: COMPONENTS MUST BE PURE

UI components MUST:

• receive data via props
• NOT fetch data
• NOT contain business logic

RULE: CONTAINER LOGIC MUST USE HOOKS

All logic MUST be extracted into hooks.

Components MUST NOT:

• manage server state
• implement side effects

RULE: COMPONENT SIZE LIMIT

Components MUST NOT exceed:

• 200 lines (soft limit)
• 300 lines (hard limit — refactor required)

🧠 HOOK RULES

RULE: ALL DATA ACCESS MUST GO THROUGH HOOKS

Hooks MUST wrap:

• queries
• mutations
• derived state

RULE: HOOK NAMING IS STRICT

Format:

• use

Examples:

• useRules
• useCreateRule
• useUserProfile

RULE: HOOKS MUST BE REUSABLE

Hooks MUST NOT depend on:

• specific UI components
• DOM structure

🗂️ ROUTING RULES

RULE: ROUTES MUST BE GROUPED BY ACCESS

Routing MUST follow:

• public routes
• authenticated routes
• admin routes

As seen in system architecture

RULE: ROUTES MUST NOT CONTAIN BUSINESS LOGIC

Routes MAY:

• compose components
• call hooks

Routes MUST NOT:

• fetch data directly
• implement API logic

🔐 AUTHENTICATION RULES

RULE: AUTH MUST BE HANDLED GLOBALLY

Authentication MUST be:

• managed via middleware or provider
• injected into API client

RULE: TOKEN HANDLING MUST BE SECURE

Preferred:

• HTTP-only cookies

Forbidden:

• storing sensitive tokens in localStorage (unless unavoidable)

⚡ PERFORMANCE RULES

RULE: UNNECESSARY RE-RENDERS MUST BE AVOIDED

Use:

• select in queries
• memoization where needed

RULE: CONDITIONAL FETCHING MUST USE QUERY OPTIONS

Use:

• enabled flag

Forbidden:

• conditional hooks

RULE: LAZY LOADING IS REQUIRED FOR SCALING

Large features MUST be lazy-loaded.

🧪 TESTING RULES

RULE: BUSINESS LOGIC MUST BE TESTED

Test:

• hooks
• services

RULE: UI TESTING IS SECONDARY

Avoid:

• testing implementation details
• fragile DOM tests

🏢 SCALABILITY RULES

RULE: FEATURES MUST SCALE INDEPENDENTLY

Each feature MUST:

• be removable without breaking system
• be deployable in isolation (future-ready)

RULE: NO TIGHT COUPLING

Forbidden:

• importing internal files across features
• shared mutable state across domains

RULE: INDEX EXPORTS ARE REQUIRED

Each feature MUST expose:

• public API via index.ts

🚫 FORBIDDEN PATTERNS

The following are STRICTLY NOT ALLOWED:

• API calls inside components
• useEffect for data fetching
• global state for server data
• monolithic folders
• cross-feature imports
• hardcoded query keys
• mixed concerns (UI + logic)

🤖 AI GENERATION RULES

AI MUST:

• generate feature-based structure
• create hooks for all data access
• use TanStack Query for server state
• separate API layer
• generate TypeScript types
• avoid inline logic in components

AI MUST NOT:

• create global services for feature logic
• fetch data inside components
• mix concerns

✅ FINAL RULE

If code violates separation of concerns, it MUST be rejected.

If data is server-derived, it MUST use TanStack Query.

If logic is reusable, it MUST be extracted into hooks.

🚀 OUTCOME

Following these rules guarantees:

• predictable architecture
• scalability across teams
• AI-compatible codebases
• clean separation of concerns
• production-ready frontend systems