adds docs on scalability

v2/community/supertokens-core/self-hosted/performance.mdx

@@ -9,9 +9,18 @@ hide_title: true
 
 # Tuning Performance
 
-### We are hard at work writing these docs... 🖊️⌛. In the meantime, you can ask us questions on [our Discord](https://supertokens.com/discord)
-
-<!-- [comment]: <> (TODO:)
-[comment]: <> (Server performance -> thread pool size)
-[comment]: <> (Database performance -> connection pool size)
-[comment]: <> (Multiple SuperTokens instances -> round robin on SDK level) -->
+If you are facing preformance issues, here are some tips to help you tune the performance of your SuperTokens setup:
+- The SuperTokens core is stateless and can be scalred horizontally. You can add more instances of the core service to handle more requests (behind a load balancer).
+- Check which part of the request cycle is slow. Is it the SuperTokens core responding slowly, or is it the backend SDK APIs responding slowly? The performance of the backend SDK API depends mainly on how you have setup your API layer (that integrates with our backend SDK) to perform. You can check which is slow by enabling debug logs in the backend SDK, and then inspecting the timestamps around the core requests. If they sum up to be much less than the total time taken for the request (from the frontend's point of view), then the bottleneck is likely in the backend SDK.
+- Check if there are any database queries that are too slow. You can do this using debugging tools provided by the PostgreSQL or MySQL databases. If you find a query that's causing issues, please reach out to us.
+- Check that the compute used to run the backend SDK, the SuperTokens core, and the database is sufficient. Using a t3.micro EC2 instance for the core should work well for even 100,000 MAUs. You can check the CPU and memory usage of the instances to see if they are being maxed out, or if you have run out of CPU credits. If they are, you can consider upgrading the instances to more powerful ones.
+- You can tune the SuperTokens core performance by setting different values for the following configs in the config.yaml file, or docker env:
+    - `max_server_pool_size`: Sets the max thread pool size for incoming http server requests. Default value is 10.
+    - `access_token_validity`: Sets the validity of the access token. Default value is 3,600 seconds (1 hour). The lower this value, the more often the refresh API will be called, increasing the load on the core.
+    - `postgresql_connection_pool_size` (if using psql): Defines the connection pool size to PostgreSQL. Default value is 10.
+    - `postgresql_minimum_idle_connections` (if using psql): Minimum number of idle connections to be kept active. If not set, minimum idle connections will be same as the connection pool size. By default, this is not set.
+    - `postgresql_idle_connection_timeout`: (if using psql): Timeout in milliseconds for the idle connections to be closed. Default is 60000 MS.
+    - `mysql_connection_pool_size` (if using mysql): Defines the connection pool size to MySQL. Default value is 10.
+    - `mysql_minimum_idle_connections` (if using mysql): Minimum number of idle connections to be kept active. If not set, minimum idle connections will be same as the connection pool size. By default, this is not set.
+    - `mysql_idle_connection_timeout`: (if using mysql): Timeout in milliseconds for the idle connections to be closed. Default is 60000 MS.
+- Check if you have access token blacklisting enabled in the backend SDK. The default is `false`, but if you have it enabled, then it means that every session verification attempt will query the supertokens core to check the database. This will add latency to the session veirifaction process and increase the load on the core. If you want to keep this to `true`, consider making it so only for non `GET` APIs for your application.

v2/emailpassword/common-customizations/core/performance.mdx

@@ -9,9 +9,18 @@ hide_title: true
 
 # Tuning Performance
 
-### We are hard at work writing these docs... 🖊️⌛. In the meantime, you can ask us questions on [our Discord](https://supertokens.com/discord)
-
-<!-- [comment]: <> (TODO:)
-[comment]: <> (Server performance -> thread pool size)
-[comment]: <> (Database performance -> connection pool size)
-[comment]: <> (Multiple SuperTokens instances -> round robin on SDK level) -->
+If you are facing preformance issues, here are some tips to help you tune the performance of your SuperTokens setup:
+- The SuperTokens core is stateless and can be scalred horizontally. You can add more instances of the core service to handle more requests (behind a load balancer).
+- Check which part of the request cycle is slow. Is it the SuperTokens core responding slowly, or is it the backend SDK APIs responding slowly? The performance of the backend SDK API depends mainly on how you have setup your API layer (that integrates with our backend SDK) to perform. You can check which is slow by enabling debug logs in the backend SDK, and then inspecting the timestamps around the core requests. If they sum up to be much less than the total time taken for the request (from the frontend's point of view), then the bottleneck is likely in the backend SDK.
+- Check if there are any database queries that are too slow. You can do this using debugging tools provided by the PostgreSQL or MySQL databases. If you find a query that's causing issues, please reach out to us.
+- Check that the compute used to run the backend SDK, the SuperTokens core, and the database is sufficient. Using a t3.micro EC2 instance for the core should work well for even 100,000 MAUs. You can check the CPU and memory usage of the instances to see if they are being maxed out, or if you have run out of CPU credits. If they are, you can consider upgrading the instances to more powerful ones.
+- You can tune the SuperTokens core performance by setting different values for the following configs in the config.yaml file, or docker env:
+    - `max_server_pool_size`: Sets the max thread pool size for incoming http server requests. Default value is 10.
+    - `access_token_validity`: Sets the validity of the access token. Default value is 3,600 seconds (1 hour). The lower this value, the more often the refresh API will be called, increasing the load on the core.
+    - `postgresql_connection_pool_size` (if using psql): Defines the connection pool size to PostgreSQL. Default value is 10.
+    - `postgresql_minimum_idle_connections` (if using psql): Minimum number of idle connections to be kept active. If not set, minimum idle connections will be same as the connection pool size. By default, this is not set.
+    - `postgresql_idle_connection_timeout`: (if using psql): Timeout in milliseconds for the idle connections to be closed. Default is 60000 MS.
+    - `mysql_connection_pool_size` (if using mysql): Defines the connection pool size to MySQL. Default value is 10.
+    - `mysql_minimum_idle_connections` (if using mysql): Minimum number of idle connections to be kept active. If not set, minimum idle connections will be same as the connection pool size. By default, this is not set.
+    - `mysql_idle_connection_timeout`: (if using mysql): Timeout in milliseconds for the idle connections to be closed. Default is 60000 MS.
+- Check if you have access token blacklisting enabled in the backend SDK. The default is `false`, but if you have it enabled, then it means that every session verification attempt will query the supertokens core to check the database. This will add latency to the session veirifaction process and increase the load on the core. If you want to keep this to `true`, consider making it so only for non `GET` APIs for your application.

v2/emailpassword/scalability.mdx

@@ -0,0 +1,48 @@
+---
+id: scalability
+title: Scalability
+hide_title: true
+---
+
+<!-- COPY DOCS -->
+<!-- ./emailpassword/scalability.mdx -->
+
+# Scalability
+
+## SuperTokens users and tenants scalability
+
+SuperTokens can handle 10s of millions of users and tenants (organizations). In fact, you can even make one tenant per user and it would work well. For most operations, the database structure and queries are designed in a way to be easily partitioned based on tenants and users. This means that as the number of tenants scale, it does not affect performance on most operations on a per tenant scale, and as the number of users scale, it does not affect performance on most operations on a per user scale.
+
+## SuperTokens core scalability
+
+The SuperTokens core service is designed to be horizontally scalable. This means that you can add more instances of the core service to handle more requests. The core service is also stateless, which means that you can add or remove instances without worrying about the state of the system.
+
+The core service is designed to be able to handle a high number of requests per second (RPS). The exact number of RPS that the core service can handle depends on the hardware that you are using, but in general, the core service is designed to be able to handle a large number of requests. 
+
+For example, the average latency of requests is ~40 milliseconds at 100-150 requests per second (6,000-10,000 RPM) as you can see below. The compute deployed is 6 instances of the SuperTokens core service, each on a t3.micro EC2 instance behind a round robin load balancer. The CPU usage of each instance is around 10%.
+
+The scale of number of end users that this can support is in the older of 1-2 million monthly active users, with a total user count of several millions more.
+
+### Average latency over 1 day
+
+<img src="/img/avg-latency.png" />
+
+### Number of requests per minute over 1 day
+
+<img src="/img/rpm.png" />
+
+
+## Database scalability
+
+SuperTokens works with PSQL and MySQL databases and one instance of the database is enough to handle 10s of millions of MAUs, easily. For example, a database with 1 million users would occupy ~ 6 MB of disk space (assuming you add no custom metadata to the user object).
+
+## Backend SDK scalability
+
+The backend SDK does not store any information on its own. It's just a "big middleware" between the frontend requests and the supertokens core. As such, its scalabillity depends entirely on the scalability of your API layer into which our backend SDK has been integrated.
+
+## Session verification scalability
+
+The access token is a JWT, and so, they are verified by our backend SDK without any network requests, making them very fast, and very scalable. The refresh token is verified by the core service, and so, the scalability of session refresh requests depends on the scalability of the core service, however, session refreshes would be a relatively rare compared to access token verification.
+
+## Need help?
+See the section on [tuning SuperTokens](./common-customizations/core/performance) to get tips on how to improve performance. 

v2/emailpassword/sidebars.js

@@ -688,6 +688,7 @@ module.exports = {
         "multi-tenant"
       ]
     },
+    "scalability",
     "rate-limits",
     {
       type: 'category',

v2/passwordless/common-customizations/core/performance.mdx

@@ -9,9 +9,18 @@ hide_title: true
 
 # Tuning Performance
 
-### We are hard at work writing these docs... 🖊️⌛. In the meantime, you can ask us questions on [our Discord](https://supertokens.com/discord)
-
-<!-- [comment]: <> (TODO:)
-[comment]: <> (Server performance -> thread pool size)
-[comment]: <> (Database performance -> connection pool size)
-[comment]: <> (Multiple SuperTokens instances -> round robin on SDK level) -->
+If you are facing preformance issues, here are some tips to help you tune the performance of your SuperTokens setup:
+- The SuperTokens core is stateless and can be scalred horizontally. You can add more instances of the core service to handle more requests (behind a load balancer).
+- Check which part of the request cycle is slow. Is it the SuperTokens core responding slowly, or is it the backend SDK APIs responding slowly? The performance of the backend SDK API depends mainly on how you have setup your API layer (that integrates with our backend SDK) to perform. You can check which is slow by enabling debug logs in the backend SDK, and then inspecting the timestamps around the core requests. If they sum up to be much less than the total time taken for the request (from the frontend's point of view), then the bottleneck is likely in the backend SDK.
+- Check if there are any database queries that are too slow. You can do this using debugging tools provided by the PostgreSQL or MySQL databases. If you find a query that's causing issues, please reach out to us.
+- Check that the compute used to run the backend SDK, the SuperTokens core, and the database is sufficient. Using a t3.micro EC2 instance for the core should work well for even 100,000 MAUs. You can check the CPU and memory usage of the instances to see if they are being maxed out, or if you have run out of CPU credits. If they are, you can consider upgrading the instances to more powerful ones.
+- You can tune the SuperTokens core performance by setting different values for the following configs in the config.yaml file, or docker env:
+    - `max_server_pool_size`: Sets the max thread pool size for incoming http server requests. Default value is 10.
+    - `access_token_validity`: Sets the validity of the access token. Default value is 3,600 seconds (1 hour). The lower this value, the more often the refresh API will be called, increasing the load on the core.
+    - `postgresql_connection_pool_size` (if using psql): Defines the connection pool size to PostgreSQL. Default value is 10.
+    - `postgresql_minimum_idle_connections` (if using psql): Minimum number of idle connections to be kept active. If not set, minimum idle connections will be same as the connection pool size. By default, this is not set.
+    - `postgresql_idle_connection_timeout`: (if using psql): Timeout in milliseconds for the idle connections to be closed. Default is 60000 MS.
+    - `mysql_connection_pool_size` (if using mysql): Defines the connection pool size to MySQL. Default value is 10.
+    - `mysql_minimum_idle_connections` (if using mysql): Minimum number of idle connections to be kept active. If not set, minimum idle connections will be same as the connection pool size. By default, this is not set.
+    - `mysql_idle_connection_timeout`: (if using mysql): Timeout in milliseconds for the idle connections to be closed. Default is 60000 MS.
+- Check if you have access token blacklisting enabled in the backend SDK. The default is `false`, but if you have it enabled, then it means that every session verification attempt will query the supertokens core to check the database. This will add latency to the session veirifaction process and increase the load on the core. If you want to keep this to `true`, consider making it so only for non `GET` APIs for your application.

v2/passwordless/scalability.mdx

@@ -0,0 +1,48 @@
+---
+id: scalability
+title: Scalability
+hide_title: true
+---
+
+<!-- COPY DOCS -->
+<!-- ./emailpassword/scalability.mdx -->
+
+# Scalability
+
+## SuperTokens users and tenants scalability
+
+SuperTokens can handle 10s of millions of users and tenants (organizations). In fact, you can even make one tenant per user and it would work well. For most operations, the database structure and queries are designed in a way to be easily partitioned based on tenants and users. This means that as the number of tenants scale, it does not affect performance on most operations on a per tenant scale, and as the number of users scale, it does not affect performance on most operations on a per user scale.
+
+## SuperTokens core scalability
+
+The SuperTokens core service is designed to be horizontally scalable. This means that you can add more instances of the core service to handle more requests. The core service is also stateless, which means that you can add or remove instances without worrying about the state of the system.
+
+The core service is designed to be able to handle a high number of requests per second (RPS). The exact number of RPS that the core service can handle depends on the hardware that you are using, but in general, the core service is designed to be able to handle a large number of requests. 
+
+For example, the average latency of requests is ~40 milliseconds at 100-150 requests per second (6,000-10,000 RPM) as you can see below. The compute deployed is 6 instances of the SuperTokens core service, each on a t3.micro EC2 instance behind a round robin load balancer. The CPU usage of each instance is around 10%.
+
+The scale of number of end users that this can support is in the older of 1-2 million monthly active users, with a total user count of several millions more.
+
+### Average latency over 1 day
+
+<img src="/img/avg-latency.png" />
+
+### Number of requests per minute over 1 day
+
+<img src="/img/rpm.png" />
+
+
+## Database scalability
+
+SuperTokens works with PSQL and MySQL databases and one instance of the database is enough to handle 10s of millions of MAUs, easily. For example, a database with 1 million users would occupy ~ 6 MB of disk space (assuming you add no custom metadata to the user object).
+
+## Backend SDK scalability
+
+The backend SDK does not store any information on its own. It's just a "big middleware" between the frontend requests and the supertokens core. As such, its scalabillity depends entirely on the scalability of your API layer into which our backend SDK has been integrated.
+
+## Session verification scalability
+
+The access token is a JWT, and so, they are verified by our backend SDK without any network requests, making them very fast, and very scalable. The refresh token is verified by the core service, and so, the scalability of session refresh requests depends on the scalability of the core service, however, session refreshes would be a relatively rare compared to access token verification.
+
+## Need help?
+See the section on [tuning SuperTokens](./common-customizations/core/performance) to get tips on how to improve performance.

v2/passwordless/sidebars.js

@@ -665,6 +665,7 @@ module.exports = {
         "multi-tenant"
       ]
     },
+    "scalability",
     "rate-limits",
     {
       type: 'category',