Additional stubs; logical design grouping

Author: sfc-gh-dmatthews

content/get-started/fundamentals/advanced-concepts.md

@@ -15,7 +15,7 @@ The basic idea behind caching is to store the results of expensive function call
 
 To cache a function in Streamlit, you need to apply a caching decorator to it. You have two choices:
 
-- `st.cache_data` is the recommended way to cache computations that return data. Use `st.cache_data` when you use a function that returns a serializable data object (e.g. str, int, float, DataFrame, dict, list). **It creates a new copy of the data at each function call**, making it safe against [mutations and race conditions](/develop/concepts/caching#mutation-and-concurrency-issues). The behavior of `st.cache_data` is what you want in most cases – so if you're unsure, start with `st.cache_data` and see if it works!
+- `st.cache_data` is the recommended way to cache computations that return data. Use `st.cache_data` when you use a function that returns a serializable data object (e.g. str, int, float, DataFrame, dict, list). **It creates a new copy of the data at each function call**, making it safe against [mutations and race conditions](/develop/concepts/logical-design/caching#mutation-and-concurrency-issues). The behavior of `st.cache_data` is what you want in most cases – so if you're unsure, start with `st.cache_data` and see if it works!
 - `st.cache_resource` is the recommended way to cache global resources like ML models or database connections. Use `st.cache_resource` when your function returns unserializable objects that you don’t want to load multiple times. **It returns the cached object itself**, which is shared across all reruns and sessions without copying or duplication. If you mutate an object that is cached using `st.cache_resource`, that mutation will exist across all reruns and sessions.
 
 Example:
@@ -36,7 +36,7 @@ Before running the code within `long_running_function`, Streamlit checks its cac
 
 <Image src="/images/caching-high-level-diagram.png" caption="Streamlit's two caching decorators and their use cases." alt="Streamlit's two caching decorators and their use cases. Use st.cache_data for anything you'd store in a database. Use st.cache_resource for anything you can't store in a database, like a connection to a database or a machine learning model." />
 
-For more information about the Streamlit caching decorators, their configuration parameters, and their limitations, see [Caching](/develop/concepts/caching).
+For more information about the Streamlit caching decorators, their configuration parameters, and their limitations, see [Caching](/develop/concepts/logical-design/caching).
 
 ## Session State
 
@@ -103,7 +103,7 @@ df = conn.query("select * from my_table")
 st.dataframe(df)
 ```
 
-Of course, you may be wondering where your username and password go. Streamlit has a convenient mechanism for [Secrets management](/develop/concepts/configuration/secrets-management). For now, let's just see how `st.connection` works very nicely with secrets. In your local project directory, you can save a `.streamlit/secrets.toml` file. You save your secrets in the toml file and `st.connection` just uses them! For example, if you have an app file `streamlit_app.py` your project directory may look like this:
+Of course, you may be wondering where your username and password go. Streamlit has a convenient mechanism for [Secrets management](/develop/concepts/logical-design/secrets-management). For now, let's just see how `st.connection` works very nicely with secrets. In your local project directory, you can save a `.streamlit/secrets.toml` file. You save your secrets in the toml file and `st.connection` just uses them! For example, if you have an app file `streamlit_app.py` your project directory may look like this:
 
 ```bash
 your-LOCAL-repository/

content/get-started/fundamentals/main-concepts.md

@@ -89,7 +89,7 @@ This can happen in two situations:
 - Whenever a user interacts with widgets in the app. For example, when dragging
   a slider, entering text in an input box, or clicking a button.
 
-Whenever a callback is passed to a widget via the `on_change` (or `on_click`) parameter, the callback will always run before the rest of your script. For details on the Callbacks API, please refer to our [Session State API Reference Guide](/develop/api-reference/caching-and-state/session-state#use-callbacks-to-update-session-state).
+Whenever a callback is passed to a widget via the `on_change` (or `on_click`) parameter, the callback will always run before the rest of your script. For details on the Callbacks API, please refer to our [Session State API Reference Guide](/develop/api-reference/control-flow/session-state#use-callbacks-to-update-session-state).
 
 And to make all of this fast and seamless, Streamlit does some heavy lifting
 for you behind the scenes. A big player in this story is the
@@ -293,7 +293,7 @@ st.text_input("Your name", key="name")
 st.session_state.name
 ```
 
-Every widget with a key is automatically added to Session State. For more information about Session State, its association with widget state, and its limitations, see [Session State API Reference Guide](/develop/api-reference/caching-and-state/session-state).
+Every widget with a key is automatically added to Session State. For more information about Session State, its association with widget state, and its limitations, see [Session State API Reference Guide](/develop/api-reference/control-flow/session-state).
 
 ### Use checkboxes to show/hide data
 

content/get-started/fundamentals/tutorials/create-an-app.md

@@ -178,7 +178,7 @@ transformational.
 <Tip>
 
 Whenever you have a long-running computation in your code, consider
-refactoring it so you can use `@st.cache_data`, if possible. Please read [Caching](/develop/concepts/caching) for more details.
+refactoring it so you can use `@st.cache_data`, if possible. Please read [Caching](/develop/concepts/logical-design/caching) for more details.
 
 </Tip>
 

content/kb/tutorials/chat.md

@@ -7,11 +7,11 @@ slug: /develop/tutorials/llms/build-conversational-apps
 
 ## Introduction
 
-The advent of large language models like GPT has revolutionized the ease of developing chat-based applications. Streamlit offers several [Chat elements](/develop/api-reference/chat), enabling you to build Graphical User Interfaces (GUIs) for conversational agents or chatbots. Leveraging [session state](/develop/concepts/session-state) along with these elements allows you to construct anything from a basic chatbot to a more advanced, ChatGPT-like experience using purely Python code.
+The advent of large language models like GPT has revolutionized the ease of developing chat-based applications. Streamlit offers several [Chat elements](/develop/api-reference/chat), enabling you to build Graphical User Interfaces (GUIs) for conversational agents or chatbots. Leveraging [session state](/develop/concepts/logical-design/session-state) along with these elements allows you to construct anything from a basic chatbot to a more advanced, ChatGPT-like experience using purely Python code.
 
 In this tutorial, we'll start by walking through Streamlit's chat elements, `st.chat_message` and `st.chat_input`. Then we'll proceed to construct three distinct applications, each showcasing an increasing level of complexity and functionality:
 
-1. First, we'll [Build a bot that mirrors your input](#build-a-bot-that-mirrors-your-input) to get a feel for the chat elements and how they work. We'll also introduce [session state](/develop/concepts/session-state) and how it can be used to store the chat history. This section will serve as a foundation for the rest of the tutorial.
+1. First, we'll [Build a bot that mirrors your input](#build-a-bot-that-mirrors-your-input) to get a feel for the chat elements and how they work. We'll also introduce [session state](/develop/concepts/logical-design/session-state) and how it can be used to store the chat history. This section will serve as a foundation for the rest of the tutorial.
 2. Next, you'll learn how to [Build a simple chatbot GUI with streaming](#build-a-simple-chatbot-gui-with-streaming).
 3. Finally, we'll [Build a ChatGPT-like app](#build-a-chatgpt-like-app) that leverages session state to remember conversational context, all within less than 50 lines of code.
 
@@ -99,7 +99,7 @@ Pretty straightforward, right? Now let's combine `st.chat_message` and `st.chat_
 
 ## Build a bot that mirrors your input
 
-In this section, we'll build a bot that mirrors or echoes your input. More specifically, the bot will respond to your input with the same message. We'll use `st.chat_message` to display the user's input and `st.chat_input` to accept user input. We'll also use [session state](/develop/concepts/session-state) to store the chat history so we can display it in the chat message container.
+In this section, we'll build a bot that mirrors or echoes your input. More specifically, the bot will respond to your input with the same message. We'll use `st.chat_message` to display the user's input and `st.chat_input` to accept user input. We'll also use [session state](/develop/concepts/logical-design/session-state) to store the chat history so we can display it in the chat message container.
 
 First, let's think about the different components we'll need to build our bot:
 
@@ -322,7 +322,7 @@ pip install openai streamlit
 
 ### Add OpenAI API key to Streamlit secrets
 
-Next, let's add our OpenAI API key to [Streamlit secrets](/develop/concepts/configuration/secrets-management). We do this by creating `.streamlit/secrets.toml` file in our project directory and adding the following lines to it:
+Next, let's add our OpenAI API key to [Streamlit secrets](/develop/concepts/logical-design/secrets-management). We do this by creating `.streamlit/secrets.toml` file in our project directory and adding the following lines to it:
 
 ```toml
 # .streamlit/secrets.toml

content/kb/tutorials/databases/_index.md

@@ -7,7 +7,7 @@ slug: /develop/tutorials/databases
 
 These step-by-step guides demonstrate how to connect Streamlit apps to various databases & APIs.
 They use Streamlit's [Secrets management](/deploy/streamlit-community-cloud/deploy-your-app/secrets-management) and
-[caching](/develop/concepts/caching) to provide secure and fast data access.
+[caching](/develop/concepts/logical-design/caching) to provide secure and fast data access.
 
 <DataSourcesContainer>
 <DataSourcesCard href="/develop/tutorials/databases/aws-s3">

content/kb/tutorials/databases/aws-s3.md

@@ -7,7 +7,7 @@ slug: /develop/tutorials/databases/aws-s3
 
 ## Introduction
 
-This guide explains how to securely access files on AWS S3 from Streamlit Community Cloud. It uses [Streamlit FilesConnection](https://github.com/streamlit/files-connection), the [s3fs](https://github.com/dask/s3fs) library and optionally Streamlit's [Secrets management](/develop/concepts/configuration/secrets-management).
+This guide explains how to securely access files on AWS S3 from Streamlit Community Cloud. It uses [Streamlit FilesConnection](https://github.com/streamlit/files-connection), the [s3fs](https://github.com/dask/s3fs) library and optionally Streamlit's [Secrets management](/develop/concepts/logical-design/secrets-management).
 
 ## Create an S3 bucket and add a file
 
@@ -110,7 +110,7 @@ for row in df.itertuples():
     st.write(f"{row.Owner} has a :{row.Pet}:")
 ```
 
-See `st.connection` above? This handles secrets retrieval, setup, result caching and retries. By default, `read()` results are cached without expiring. In this case, we set `ttl=600` to ensure the file contents is cached for no longer than 10 minutes. You can also set `ttl=0` to disable caching. Learn more in [Caching](/develop/concepts/caching).
+See `st.connection` above? This handles secrets retrieval, setup, result caching and retries. By default, `read()` results are cached without expiring. In this case, we set `ttl=600` to ensure the file contents is cached for no longer than 10 minutes. You can also set `ttl=0` to disable caching. Learn more in [Caching](/develop/concepts/logical-design/caching).
 
 If everything worked out (and you used the example file given above), your app should look like this:
 

content/kb/tutorials/databases/bigquery.md

@@ -135,7 +135,7 @@ for row in rows:
     st.write("✍️ " + row['word'])
 ```
 
-See `st.cache_data` above? Without it, Streamlit would run the query every time the app reruns (e.g. on a widget interaction). With `st.cache_data`, it only runs when the query changes or after 10 minutes (that's what `ttl` is for). Watch out: If your database updates more frequently, you should adapt `ttl` or remove caching so viewers always see the latest data. Learn more in [Caching](/develop/concepts/caching).
+See `st.cache_data` above? Without it, Streamlit would run the query every time the app reruns (e.g. on a widget interaction). With `st.cache_data`, it only runs when the query changes or after 10 minutes (that's what `ttl` is for). Watch out: If your database updates more frequently, you should adapt `ttl` or remove caching so viewers always see the latest data. Learn more in [Caching](/develop/concepts/logical-design/caching).
 
 Alternatively, you can use pandas to read from BigQuery right into a dataframe! Follow all the above steps, install the [pandas-gbq](https://pandas-gbq.readthedocs.io/en/latest/index.html) library (don't forget to add it to `requirements.txt`!), and call `pandas.read_gbq(query, credentials=credentials)`. More info [in the pandas docs](https://pandas.pydata.org/docs/reference/api/pandas.read_gbq.html).
 

content/kb/tutorials/databases/gcs.md

@@ -7,7 +7,7 @@ slug: /develop/tutorials/databases/gcs
 
 ## Introduction
 
-This guide explains how to securely access files on Google Cloud Storage from Streamlit Community Cloud. It uses [Streamlit FilesConnection](https://github.com/streamlit/files-connection), the [gcsfs](https://github.com/fsspec/gcsfs) library and Streamlit's [Secrets management](/develop/concepts/configuration/secrets-management).
+This guide explains how to securely access files on Google Cloud Storage from Streamlit Community Cloud. It uses [Streamlit FilesConnection](https://github.com/streamlit/files-connection), the [gcsfs](https://github.com/fsspec/gcsfs) library and Streamlit's [Secrets management](/develop/concepts/logical-design/secrets-management).
 
 ## Create a Google Cloud Storage bucket and add a file
 
@@ -135,7 +135,7 @@ for row in df.itertuples():
     st.write(f"{row.Owner} has a :{row.Pet}:")
 ```
 
-See `st.connection` above? This handles secrets retrieval, setup, result caching and retries. By default, `read()` results are cached without expiring. In this case, we set `ttl=600` to ensure the file contents is cached for no longer than 10 minutes. You can also set `ttl=0` to disable caching. Learn more in [Caching](/develop/concepts/caching).
+See `st.connection` above? This handles secrets retrieval, setup, result caching and retries. By default, `read()` results are cached without expiring. In this case, we set `ttl=600` to ensure the file contents is cached for no longer than 10 minutes. You can also set `ttl=0` to disable caching. Learn more in [Caching](/develop/concepts/logical-design/caching).
 
 If everything worked out (and you used the example file given above), your app should look like this:
 

content/kb/tutorials/databases/mongodb.md

@@ -96,7 +96,7 @@ for item in items:
     st.write(f"{item['name']} has a :{item['pet']}:")
 ```
 
-See `st.cache_data` above? Without it, Streamlit would run the query every time the app reruns (e.g. on a widget interaction). With `st.cache_data`, it only runs when the query changes or after 10 minutes (that's what `ttl` is for). Watch out: If your database updates more frequently, you should adapt `ttl` or remove caching so viewers always see the latest data. Learn more in [Caching](/develop/concepts/caching).
+See `st.cache_data` above? Without it, Streamlit would run the query every time the app reruns (e.g. on a widget interaction). With `st.cache_data`, it only runs when the query changes or after 10 minutes (that's what `ttl` is for). Watch out: If your database updates more frequently, you should adapt `ttl` or remove caching so viewers always see the latest data. Learn more in [Caching](/develop/concepts/logical-design/caching).
 
 If everything worked out (and you used the example data we created above), your app should look like this:
 

content/kb/tutorials/databases/mssql.md

@@ -186,7 +186,7 @@ for row in rows:
 
 ```
 
-See `st.cache_data` above? Without it, Streamlit would run the query every time the app reruns (e.g. on a widget interaction). With `st.cache_data`, it only runs when the query changes or after 10 minutes (that's what `ttl` is for). Watch out: If your database updates more frequently, you should adapt `ttl` or remove caching so viewers always see the latest data. Learn more in [Caching](/develop/concepts/caching).
+See `st.cache_data` above? Without it, Streamlit would run the query every time the app reruns (e.g. on a widget interaction). With `st.cache_data`, it only runs when the query changes or after 10 minutes (that's what `ttl` is for). Watch out: If your database updates more frequently, you should adapt `ttl` or remove caching so viewers always see the latest data. Learn more in [Caching](/develop/concepts/logical-design/caching).
 
 If everything worked out (and you used the example table we created above), your app should look like this:
 

content/kb/tutorials/databases/mysql.md

@@ -7,7 +7,7 @@ slug: /develop/tutorials/databases/mysql
 
 ## Introduction
 
-This guide explains how to securely access a **_remote_** MySQL database from Streamlit Community Cloud. It uses [st.connection](/develop/api-reference/connections/st.connection) and Streamlit's [Secrets management](/develop/concepts/configuration/secrets-management). The below example code will **only work on Streamlit version >= 1.28**, when `st.connection` was added.
+This guide explains how to securely access a **_remote_** MySQL database from Streamlit Community Cloud. It uses [st.connection](/develop/api-reference/connections/st.connection) and Streamlit's [Secrets management](/develop/concepts/logical-design/secrets-management). The below example code will **only work on Streamlit version >= 1.28**, when `st.connection` was added.
 
 ## Create a MySQL database
 
@@ -35,7 +35,7 @@ INSERT INTO mytable VALUES ('Mary', 'dog'), ('John', 'cat'), ('Robert', 'bird');
 
 ## Add username and password to your local app secrets
 
-Your local Streamlit app will read secrets from a file `.streamlit/secrets.toml` in your app's root directory. Learn more about [Streamlit secrets management here](/develop/concepts/configuration/secrets-management). Create this file if it doesn't exist yet and add the database name, user, and password of your MySQL server as shown below:
+Your local Streamlit app will read secrets from a file `.streamlit/secrets.toml` in your app's root directory. Learn more about [Streamlit secrets management here](/develop/concepts/logical-design/secrets-management). Create this file if it doesn't exist yet and add the database name, user, and password of your MySQL server as shown below:
 
 ```toml
 # .streamlit/secrets.toml
@@ -93,7 +93,7 @@ for row in df.itertuples():
     st.write(f"{row.name} has a :{row.pet}:")
 ```
 
-See `st.connection` above? This handles secrets retrieval, setup, query caching and retries. By default, `query()` results are cached without expiring. In this case, we set `ttl=600` to ensure the query result is cached for no longer than 10 minutes. You can also set `ttl=0` to disable caching. Learn more in [Caching](/develop/concepts/caching).
+See `st.connection` above? This handles secrets retrieval, setup, query caching and retries. By default, `query()` results are cached without expiring. In this case, we set `ttl=600` to ensure the query result is cached for no longer than 10 minutes. You can also set `ttl=0` to disable caching. Learn more in [Caching](/develop/concepts/logical-design/caching).
 
 If everything worked out (and you used the example table we created above), your app should look like this: