docs: add guidance for scaling state

docs/advanced_onboarding/code_structure.md

@@ -13,6 +13,10 @@ The main app module is responsible for importing all other modules that make up
 
 As applications scale, effective organization is crucial. This is achieved by breaking the application down into smaller, manageable modules and organizing them into logical packages that avoid circular dependencies.
 
+The examples below use page and component packages to introduce the mechanics. For a larger application, prefer
+feature packages that keep each page or workflow close to its State, events, components, services, and tests. See
+[Scaling State](/docs/state-structure/scaling-state) for the recommended feature layout and State ownership rules.
+
 In the following documentation there will be an app with an `app_name` of `example_big_app`. The main module would be `example_big_app/example_big_app.py`.
 
 In the [Putting it all together](#putting-it-all-together) section there is a visual of the project folder structure to help follow along with the examples below.
@@ -31,10 +35,11 @@ import reflex as rx
 from ..state import AuthState
 
 
-class LoginState(AuthState):
+class LoginState(rx.State):
     @rx.event
-    def handle_submit(self, form_data):
-        self.logged_in = authenticate(form_data["username"], form_data["password"])
+    async def handle_submit(self, form_data):
+        auth = await self.get_state(AuthState)
+        auth.logged_in = authenticate(form_data["username"], form_data["password"])
 
 
 def login_field(name: str, **input_props):
@@ -99,6 +104,9 @@ Most pages will use State in some capacity. You should avoid adding vars to a
 shared state that will only be used in a single page. Instead, define a new
 subclass of `rx.State` and keep it in the same module as the page.
 
+As the page grows, its page function and State may move into separate modules inside the same feature package. Keep
+the State directly under `rx.State` unless a parent-child loading relationship is intentional.
+
 ### Accessing other States
 
 As of Reflex 0.4.3, any event handler can get access to an instance of any other
@@ -210,8 +218,9 @@ module should not import other modules in the app.
 The primary mechanism for reusing components in Reflex is to define a function that returns
 the component, then simply call it where that functionality is needed.
 
-Component functions typically should not take any State classes as arguments, but prefer
-to import the needed state and access the vars on the class directly.
+A component used only inside one feature may import and bind directly to that feature's State.
+A component shared between features should accept the values and event handlers it needs rather
+than importing or accepting an application State class.
 
 ### Memoize Functions for Improved Performance
 

docs/ai_builder/integrations/agent_toolkit.md

@@ -63,6 +63,7 @@ You do not need an API key to read Reflex documentation. Start by deciding how y
 
 - For local app development, use Python 3.10 or newer and a project virtual environment.
 - For current documentation context, give the assistant Markdown docs or `llms.txt`.
+- For a large or multi-page app, start with [Scaling State](/docs/state-structure/scaling-state/), [Project Structure (Advanced)](/docs/advanced-onboarding/code-structure/), and [State Structure](/docs/state-structure/overview/).
 - For structured tool access, use the Reflex MCP integration.
 - For repeatable agent behavior, install Reflex Agent Skills.
 - For a browser-based AI builder, use Reflex Build.
@@ -83,6 +84,8 @@ https://reflex.dev/docs/ai/integrations/agent-toolkit.md
 
 Use this when an agent needs one focused page.
 
+For architecture work in a large or multi-page app, send the agent directly to the [Scaling State Markdown page](https://reflex.dev/docs/state-structure/scaling-state.md). It links the State ownership decisions to the advanced project-structure and State-structure guidance.
+
 
 ## llms.txt
 
@@ -149,6 +152,13 @@ Work on this existing Reflex app. First inspect the project structure and curren
 ```
 
 
+## Large App
+
+```text
+Plan or refactor this large, multi-page Reflex app. Before changing code, read the current Scaling State, Project Structure (Advanced), and State Structure guides. Map page and feature ownership plus cross-State dependencies, choose boundaries using those guides, make the smallest coherent change, and validate it with reflex compile --dry and the project's tests.
+```
+
+
 ## Debugging
 
 ```text

docs/ai_builder/integrations/agents_md.md

@@ -65,10 +65,13 @@ The template covers Reflex-wide setup. Below it, add anything else the assistant
 - Internal conventions and code style.
 - Required lint, type-check, or test commands.
 - Folder layout and where new code should go.
+- State ownership, page or feature boundaries, and permitted cross-State dependencies.
 - Hosting or deployment notes.
 
 Keep entries short and imperative — assistants follow concise, direct instructions more reliably than long paragraphs.
 
+For large or multi-page apps, direct the assistant to read [Scaling State](/docs/state-structure/scaling-state/), [Project Structure (Advanced)](/docs/advanced-onboarding/code-structure/), and [State Structure](/docs/state-structure/overview/) before it introduces State inheritance or reorganizes modules.
+
 ## Keeping Files Updated
 
 Reflex evolves quickly. If `reflex init` created your `AGENTS.md`, re-running `reflex init` refreshes the content between the managed markers while preserving everything you added outside them.

docs/ai_builder/integrations/skills.md

@@ -18,7 +18,7 @@ def skills_summary_cards() -> rx.Component:
         _summary_card(
             "Docs",
             "Current Reflex guidance",
-            "Point agents to the right Reflex docs for state, vars, components, routing, styling, deployment, and more.",
+            "Point agents to the right Reflex docs for state architecture, large-app structure, vars, components, routing, styling, deployment, and more.",
         ),
         _summary_card(
             "Setup",
@@ -52,6 +52,7 @@ skills_summary_cards()
 Use Reflex Agent Skills when you want an AI assistant to follow Reflex-specific workflows instead of relying only on general training data. They are especially useful when an assistant needs to:
 
 - Build or edit a Reflex app.
+- Plan or refactor State boundaries in a large, multi-page app.
 - Set up a new Python environment.
 - Decide which Reflex docs apply to the task.
 - Compile, run, restart, or debug a local Reflex server.
@@ -166,6 +167,16 @@ The `reflex-docs` skill gives the assistant a Reflex-specific reference map and
 
 It also reminds the assistant to prefer current Reflex documentation over pre-trained knowledge when there is a conflict.
 
+### Large Apps
+
+When using the docs skill for a large or multi-page app, give the assistant these pages before it creates new State inheritance or reorganizes modules:
+
+1. [Scaling State](/docs/state-structure/scaling-state/)
+2. [Project Structure (Advanced)](/docs/advanced-onboarding/code-structure/)
+3. [State Structure](/docs/state-structure/overview/)
+
+This sequence gives the assistant the architecture decision guide first, followed by the module-layout and State API details needed to apply it.
+
 
 ## Setup
 
@@ -253,7 +264,8 @@ Using `-sTCP:LISTEN` helps the assistant target the server process instead of br
 1. Open your Reflex project in an agent-enabled editor.
 2. Ask for the feature, bug fix, or refactor you want.
 3. The assistant should load `reflex-docs` when it sees Reflex code.
-4. For local verification, the assistant should compile the app with `reflex compile --dry` or run it with the process-management workflow.
+4. For a multi-page app or substantial State refactor, the assistant should read [Scaling State](/docs/state-structure/scaling-state/) and its linked structure guides before changing architecture.
+5. For local verification, the assistant should compile the app with `reflex compile --dry` or run it with the process-management workflow.
 
 
 ## Debugging

docs/app/agent_files/_plugin.py

@@ -35,6 +35,14 @@
 
 > Reflex is a Python framework for building full-stack web apps. Use this index to find agent-readable Markdown docs, or see [llms-full.txt]({llms_full_txt_url}) for the complete docs in one file.
 
+## Large App Architecture
+
+For multi-page apps or apps with substantial state, read these guides before choosing module and State boundaries:
+
+1. [Scaling State]({scaling_state_url})
+2. [Project Structure (Advanced)]({code_structure_url})
+3. [State Structure]({state_structure_url})
+
 ## Docs
 """
 
@@ -45,16 +53,24 @@
 This file stitches together the full Reflex documentation as Markdown for AI agents and LLM indexing.
 
 For a navigable index with links to individual docs pages, see [llms.txt]({llms_txt_url}).
+
+For multi-page apps or apps with substantial state, start with [Scaling State]({scaling_state_url}), then review [Project Structure (Advanced)]({code_structure_url}) and [State Structure]({state_structure_url}) before choosing module and State boundaries.
 """
 
 MARKDOWN_DIRECTIVE = (
     "> For AI agents: the complete documentation index is at "
     "[llms.txt]({llms_txt_url}). Markdown versions are available by appending "
-    "`.md` or sending `Accept: text/markdown`."
+    "`.md` or sending `Accept: text/markdown`. For large or multi-page apps, "
+    "start with [Scaling State]({scaling_state_url})."
 )
 PUBLIC_LLMS_TXT_URL = "https://reflex.dev/docs/llms.txt"
+PUBLIC_SCALING_STATE_URL = "https://reflex.dev/docs/state-structure/scaling-state.md"
 PUBLIC_EVENT_TRIGGERS_URL = "https://reflex.dev/docs/api-reference/event-triggers/"
 
+SCALING_STATE_DOC_PATH = Path("state-structure/scaling-state.md")
+CODE_STRUCTURE_DOC_PATH = Path("advanced-onboarding/code-structure.md")
+STATE_STRUCTURE_DOC_PATH = Path("state-structure/overview.md")
+
 
 @dataclass(frozen=True)
 class MarkdownFileEntry:
@@ -271,7 +287,10 @@ def _markdown_directive() -> str:
     Returns:
         The markdown blockquote directive.
     """
-    return MARKDOWN_DIRECTIVE.format(llms_txt_url=PUBLIC_LLMS_TXT_URL).strip()
+    return MARKDOWN_DIRECTIVE.format(
+        llms_txt_url=PUBLIC_LLMS_TXT_URL,
+        scaling_state_url=PUBLIC_SCALING_STATE_URL,
+    ).strip()
 
 
 def generate_markdown_file_content(entry: MarkdownFileEntry) -> str:
@@ -741,6 +760,9 @@ def generate_llms_txt(
     lines = [
         LLMS_TXT_INTRO.format(
             llms_full_txt_url=_llms_url_for_path(Path("llms-full.txt")),
+            scaling_state_url=_llms_url_for_path(SCALING_STATE_DOC_PATH),
+            code_structure_url=_llms_url_for_path(CODE_STRUCTURE_DOC_PATH),
+            state_structure_url=_llms_url_for_path(STATE_STRUCTURE_DOC_PATH),
         ).strip(),
         "",
     ]
@@ -773,6 +795,9 @@ def generate_llms_full_txt(
         LLMS_FULL_INTRO.format(
             docs_home_url=_docs_home_url(),
             llms_txt_url=_llms_url_for_path(Path("llms.txt")),
+            scaling_state_url=_llms_url_for_path(SCALING_STATE_DOC_PATH),
+            code_structure_url=_llms_url_for_path(CODE_STRUCTURE_DOC_PATH),
+            state_structure_url=_llms_url_for_path(STATE_STRUCTURE_DOC_PATH),
         ).strip(),
         "",
     ]

docs/app/reflex_docs/redirects.py

@@ -0,0 +1,34 @@
+"""Redirect mappings for the docs site."""
+
+from collections.abc import Iterable
+
+from reflex_site_shared.route import Route
+
+
+def get_redirects(routes: Iterable[Route]) -> list[tuple[str, str]]:
+    """Return static redirects and aliases generated from registered routes.
+
+    Args:
+        routes: Route subset used to generate ``/ai-builder/`` aliases.
+
+    Returns:
+        All static redirects plus aliases for the supplied route subset.
+    """
+    return [
+        ("/ai/integrations/ai-onboarding/", "/ai/integrations/agent-toolkit/"),
+        ("/ai-builder/integrations/ai-onboarding/", "/ai/integrations/agent-toolkit/"),
+        *[
+            (route.path.replace("/ai/", "/ai-builder/", 1), route.path)
+            for route in routes
+            if route.path.startswith("/ai/")
+        ],
+        ("/ai/features/ide/", "/ai/features/editor-modes/"),
+        ("/ai-builder/features/ide/", "/ai/features/editor-modes/"),
+        ("/ai/features/customization/", "/ai/features/design-systems/"),
+        ("/ai-builder/features/customization/", "/ai/features/design-systems/"),
+        ("/hosting/adding-members/", "/hosting/project-members/"),
+        ("/hosting/projects/", "/hosting/project-members/"),
+        ("/authentication/authentication-overview/", "/enterprise/auth/overview/"),
+        ("/substates/overview/", "/state-structure/overview/"),
+        ("/substates/component-state/", "/state-structure/component-state/"),
+    ]

docs/app/reflex_docs/reflex_docs.py

@@ -17,6 +17,7 @@
 from reflex_site_shared.telemetry import get_pixel_website_trackers
 
 from reflex_docs.pages import page404, routes
+from reflex_docs.redirects import get_redirects
 from reflex_docs.whitelist import _check_whitelisted_path
 
 # This number discovered by trial and error on Windows 11 w/ Node 18, any
@@ -168,24 +169,7 @@ def _canonical_url(path: str) -> str:
         app.add_page(**page_args)
 
 # Add redirects.
-redirects = [
-    ("/ai/integrations/ai-onboarding/", "/ai/integrations/agent-toolkit/"),
-    ("/ai-builder/integrations/ai-onboarding/", "/ai/integrations/agent-toolkit/"),
-    *[
-        (route.path.replace("/ai/", "/ai-builder/", 1), route.path)
-        for route in routes
-        if route.path.startswith("/ai/")
-    ],
-]
-redirects.extend([
-    ("/ai/features/ide/", "/ai/features/editor-modes/"),
-    ("/ai-builder/features/ide/", "/ai/features/editor-modes/"),
-    ("/ai/features/customization/", "/ai/features/design-systems/"),
-    ("/ai-builder/features/customization/", "/ai/features/design-systems/"),
-    ("/hosting/adding-members/", "/hosting/project-members/"),
-    ("/hosting/projects/", "/hosting/project-members/"),
-    ("/authentication/authentication-overview/", "/enterprise/auth/overview/"),
-])
+redirects = get_redirects(routes)
 
 
 def _redirect_page():

docs/app/reflex_docs/templates/docpage/sidebar/sidebar_items/learn.py

@@ -165,6 +165,7 @@ def get_sidebar_items_backend():
                 state_structure.component_state,
                 state_structure.mixins,
                 state_structure.shared_state,
+                state_structure.scaling_state,
             ],
         ),
         create_item(