powersync-ja · benitav · Jul 29, 2025 · Jul 29, 2025 · Jul 29, 2025 · Jul 29, 2025
diff --git a/architecture/architecture-overview.mdx b/architecture/architecture-overview.mdx
@@ -4,7 +4,7 @@ description: "The core components of PowerSync are the service and client SDKs"
 ---
 
 <Frame>
-  <img src="/images/powersync-diagram-architecture-overview.png" />
+  <img src="/images/architecture/powersync-docs-diagram-architecture-overview.png" />
 </Frame>
 
 The [PowerSync Service](/architecture/powersync-service) and client SDK operate in unison to keep client-side SQLite databases in sync with a backend database. Learn about their architecture:

diff --git a/architecture/client-architecture.mdx b/architecture/client-architecture.mdx
@@ -19,13 +19,13 @@ A developer configures [Sync Rules](/usage/sync-rules) for their PowerSync insta
 The PowerSync Service connects directly to the backend database and uses a change stream to hydrate dynamic data partitions, called [sync buckets](/usage/sync-rules/organize-data-into-buckets). Sync buckets are used to partition data according to the configured Sync Rules. (In most use cases, only a subset of data is required in a client's database and not a copy of the entire backend database.)
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-006 (2).png" />
+  <img src="/images/architecture/powersync-docs-diagram-client-architecture-001.png" />
 </Frame>
 
 The local SQLite database embedded in the PowerSync SDK is automatically kept in sync with the backend database, based on the [Sync Rules](/usage/sync-rules) configured by the developer:
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-007 (2).png" />
+  <img src="/images/architecture/powersync-docs-diagram-client-architecture-002.png" />
 </Frame>
 
 #### Writing Data
@@ -35,7 +35,7 @@ Client-side data modifications, namely updates, deletes and inserts, are persist
 Each entry in the queue is processed by writing the entry to your existing backend application API, using a function [defined by you](/installation/client-side-setup/integrating-with-your-backend) (the developer). This is to ensure that existing backend business logic is honored when uploading data changes. For more information, see the section on [integrating with your backend](/installation/client-side-setup/integrating-with-your-backend).
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-008 (3).png" />
+  <img src="/images/architecture/powersync-docs-diagram-client-architecture-003.png" />
 </Frame>
 
 ### Schema
@@ -67,5 +67,5 @@ Most rows will be present in at least two tables — the `ps_data__<table>` tabl
 The copy in `ps_oplog` may be newer than the one in `ps_data__<table>`. Only when a full checkpoint has been downloaded, will the data be copied over to the individual tables. If multiple rows with the same table and id has been synced, only one will be preserved (the one with the highest `op_id`).
 
 <Note>
-  If you run into limitations with the above JSON-based SQLite view system, check out [this experimental feature](/usage/use-case-examples/raw-tables) which allows you to define and manage raw SQLite tables to work around some limitations. We are actively seeking feedback about this functionality.
+  If you run into limitations with the above JSON-based SQLite view system, check out [the Raw Tables experimental feature](/usage/use-case-examples/raw-tables) which allows you to define and manage raw SQLite tables to work around some limitations. We are actively seeking feedback about this functionality.
 </Note>
diff --git a/images/architecture/powersync-docs-diagram-architecture-overview.png b/images/architecture/powersync-docs-diagram-architecture-overview.png
diff --git a/images/architecture/powersync-docs-diagram-client-architecture-001.png b/images/architecture/powersync-docs-diagram-client-architecture-001.png
diff --git a/images/architecture/powersync-docs-diagram-client-architecture-002.png b/images/architecture/powersync-docs-diagram-client-architecture-002.png
diff --git a/images/architecture/powersync-docs-diagram-client-architecture-003.png b/images/architecture/powersync-docs-diagram-client-architecture-003.png
diff --git a/images/authentication/powersync-docs-diagram-authentication-setup-001.png b/images/authentication/powersync-docs-diagram-authentication-setup-001.png
diff --git a/images/authentication/powersync-docs-diagram-authentication-setup-002.png b/images/authentication/powersync-docs-diagram-authentication-setup-002.png
diff --git a/images/authentication/powersync-docs-diagram-authentication-setup-003.png b/images/authentication/powersync-docs-diagram-authentication-setup-003.png
diff --git a/images/authentication/powersync-docs-diagram-authentication-setup-004.png b/images/authentication/powersync-docs-diagram-authentication-setup-004.png
diff --git a/images/installation/powersync-docs-diagram-app-backend-setup.png b/images/installation/powersync-docs-diagram-app-backend-setup.png
diff --git a/images/integration-1.png b/images/integration-1.png
diff --git a/images/integration-20.png b/images/integration-20.png
diff --git a/images/integration-21.png b/images/integration-21.png
diff --git a/images/integration-33.png b/images/integration-33.png
diff --git a/images/integration-54.avif b/images/integration-54.avif
diff --git a/images/integration-guides/supabase/diagram-docs-supabase-integration.png b/images/integration-guides/supabase/diagram-docs-supabase-integration.png
diff --git a/images/integration-guides/supabase/powersync-docs-diagram-supabase-integration.png b/images/integration-guides/supabase/powersync-docs-diagram-supabase-integration.png
diff --git a/images/overview-1.webp b/images/overview-1.webp
diff --git a/images/overview-2.webp b/images/overview-2.webp
diff --git a/images/overview-3.webp b/images/overview-3.webp
diff --git a/images/overview-4.webp b/images/overview-4.webp
diff --git a/images/overview-5.webp b/images/overview-5.webp
diff --git a/images/overview-6.webp b/images/overview-6.webp
diff --git a/images/overview-7.webp b/images/overview-7.webp
diff --git a/images/powersync-architecture-diagram-self-host.png b/images/powersync-architecture-diagram-self-host.png
diff --git a/images/powersync-diagram-architecture-overview.png b/images/powersync-diagram-architecture-overview.png
diff --git a/images/powersync-docs-app-backend-setup-diagram (2).png b/images/powersync-docs-app-backend-setup-diagram (2).png
diff --git a/images/powersync-docs-architecture-diagram-001 (1).png b/images/powersync-docs-architecture-diagram-001 (1).png
diff --git a/images/powersync-docs-architecture-diagram-002 (2).png b/images/powersync-docs-architecture-diagram-002 (2).png
diff --git a/images/powersync-docs-architecture-diagram-004 (2).png b/images/powersync-docs-architecture-diagram-004 (2).png
diff --git a/images/powersync-docs-architecture-diagram-005 (2).png b/images/powersync-docs-architecture-diagram-005 (2).png
diff --git a/images/powersync-docs-architecture-diagram-006 (2).png b/images/powersync-docs-architecture-diagram-006 (2).png
diff --git a/images/powersync-docs-architecture-diagram-007 (2).png b/images/powersync-docs-architecture-diagram-007 (2).png
diff --git a/images/powersync-docs-architecture-diagram-008 (3).png b/images/powersync-docs-architecture-diagram-008 (3).png
diff --git a/images/powersync-docs-sync-rules-diagram-001 (2).png b/images/powersync-docs-sync-rules-diagram-001 (2).png
diff --git a/images/powersync-docs-sync-rules-diagram-001 (3).png b/images/powersync-docs-sync-rules-diagram-001 (3).png
diff --git a/images/powersync-docs-sync-rules-diagram-002.png b/images/powersync-docs-sync-rules-diagram-002.png
diff --git a/images/powersync-docs-sync-rules-diagram-003.png b/images/powersync-docs-sync-rules-diagram-003.png
diff --git a/images/resources-1.png b/images/resources-1.png
diff --git a/images/resources-2.png b/images/resources-2.png
diff --git a/images/resources-3.png b/images/resources-3.png
diff --git a/images/resources-5.avif b/images/resources-5.avif
diff --git a/images/self-hosting/powersync-architecture-diagram-self-host.png b/images/self-hosting/powersync-architecture-diagram-self-host.png
diff --git a/images/usage-10.webp b/images/usage-10.webp
diff --git a/images/usage-12.png b/images/usage-12.png
diff --git a/images/usage-13.avif b/images/usage-13.avif
diff --git a/images/usage-15.avif b/images/usage-15.avif
diff --git a/images/usage-16.avif b/images/usage-16.avif
diff --git a/images/usage-8.webp b/images/usage-8.webp
diff --git a/images/usage-9.webp b/images/usage-9.webp
diff --git a/images/usage/sync-rules/powersync-docs-diagram-sync-rules-001.png b/images/usage/sync-rules/powersync-docs-diagram-sync-rules-001.png
diff --git a/images/usage/sync-rules/powersync-docs-diagram-sync-rules-002.png b/images/usage/sync-rules/powersync-docs-diagram-sync-rules-002.png
diff --git a/images/usage/sync-rules/powersync-docs-diagram-sync-rules-003.png b/images/usage/sync-rules/powersync-docs-diagram-sync-rules-003.png
diff --git a/images/usage/use-case-prioritized.png b/images/usage/use-case-prioritized.png
diff --git a/installation/app-backend-setup.mdx b/installation/app-backend-setup.mdx
@@ -11,7 +11,7 @@ When you integrate PowerSync into your app project, PowerSync relies on that "ba
 2. **Authentication integration:** Your backend is responsible for securely generating the [JWTs](/installation/authentication-setup) used by the PowerSync Client SDK to authenticate with the [PowerSync Service](/architecture/powersync-service).
 
 <Frame caption="An overview of how PowerSync interacts with your backend application.">
-  <img src="/images/powersync-docs-app-backend-setup-diagram (2).png"/>
+  <img src="/images/installation/powersync-docs-diagram-app-backend-setup.png"/>
 </Frame>
 
 

diff --git a/installation/authentication-setup.mdx b/installation/authentication-setup.mdx
@@ -9,25 +9,25 @@
 
 Before using PowerSync, an application's existing architecture may look like this:
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-001 (1).png"/>
+  <img src="/images/authentication/powersync-docs-diagram-authentication-setup-001.png"/>
 </Frame>
 
 The [PowerSync Service](/architecture/powersync-service) uses database native credentials and authenticates directly against the [backend database](/installation/database-setup) using the configured credentials:
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-002 (2).png"/>
+  <img src="/images/authentication/powersync-docs-diagram-authentication-setup-002.png"/>
 </Frame>
 
 When the PowerSync client SDK is included in an app project, it uses [existing app-to-backend](/installation/app-backend-setup) authentication to [retrieve a JSON Web Token (JWT)](/installation/authentication-setup):
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-004 (2).png"/>
+  <img src="/images/authentication/powersync-docs-diagram-authentication-setup-003.png"/>
 </Frame>
 
 The PowerSync client SDK uses the retrieved JWT to authenticate directly against the PowerSync Service:
 
 <Frame>
-  <img src="/images/powersync-docs-architecture-diagram-005 (2).png"/>
+  <img src="/images/authentication/powersync-docs-diagram-authentication-setup-004.png"/>
 </Frame>
 
 Users are not persisted in PowerSync, and there is no server-to-server communication used for client authentication.
@@ -47,8 +47,8 @@
 | **Auth0** | `https://{auth0-domain}/.well-known/jwks.json` | JWT Audience: PowerSync instance URL | [Auth0 Setup](/installation/authentication-setup/auth0) |
 | **Clerk** | `https://{yourClerkDomain}/.well-known/jwks.json` |Additional configuration may be required | [Clerk Documentation](https://clerk.com/docs/backend-requests/making/jwt-templates#create-a-jwt-template) |
 | **Stytch** | `https://{live_or_test}.stytch.com/v1/sessions/jwks/{project-id}` | Additional configuration may be required | [Stytch Documentation](https://stytch.com/docs/api/jwks-get) |
 | **Keycloak** | `https://{your-keycloak-domain}/auth/realms/{realm-name}/protocol/openid-connect/certs` | Additional configuration may be required | [Keycloak Documentation](https://documentation.cloud-iam.com/how-to-guides/configure-remote-jkws.html) |
 | **Amazon Cognito** | `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json` | Additional configuration may be required | [Cognito Documentation](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html) |
 | **Azure AD** | `https://login.microsoftonline.com/{tenantId}/discovery/v2.0/keys` | Additional configuration may be required | [Azure AD Documentation](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens) |
 | **Google Identity** | `https://www.googleapis.com/oauth2/v3/certs` | Additional configuration may be required | [Google Identity Documentation](https://developers.google.com/identity/openid-connect/openid-connect#discovery) |
 | **SuperTokens** | `https://{YOUR_SUPER_TOKENS_CORE_CONNECTION_URI}/.well-known/jwks.json` | Additional configuration may be required | [SuperTokens Documentation](https://supertokens.com/docs/quickstart/integrations/aws-lambda/session-verification/using-jwt-authorizer) |

diff --git a/integration-guides/supabase-+-powersync.mdx b/integration-guides/supabase-+-powersync.mdx
@@ -35,7 +35,7 @@ For web apps, this guide assumes that you have [pnpm](https://pnpm.io/installati
 
 Upon successful integration of Supabase + PowerSync, your system architecture will look like this: (click to enlarge image)
 <Frame>
-  <img src="/images/integration-guides/supabase/diagram-docs-supabase-integration.png"/>
+  <img src="/images/integration-guides/supabase/powersync-docs-diagram-supabase-integration.png"/>
 </Frame>
 The local SQLite database embedded in the PowerSync SDK is automatically kept in sync with the Supabase Postgres database (based on configured sync rules as you will see later in this guide). Client-side data modifications are persisted in the local SQLite database as well as stored in an upload queue that gets processed via the Supabase client library when network connectivity is available. Therefore reads and writes can happen in the app regardless of whether the user is online or offline, by using the local SQLite database.
 

diff --git a/self-hosting/installation.mdx b/self-hosting/installation.mdx
@@ -8,7 +8,7 @@ sidebarTitle: Overview
 The typical components of a self-hosted production environment are:
 
 <Frame caption="Self-hosted PowerSync architecture">
-  ![](/images/powersync-architecture-diagram-self-host.png)
+  ![](/images/self-hosting/powersync-architecture-diagram-self-host.png)
 </Frame>
 
 The self-hosted deployment is run via Docker. A Docker image is distributed via [Docker Hub](https://hub.docker.com/r/journeyapps/powersync-service). Run PowerSync using:

diff --git a/usage/sync-rules.mdx b/usage/sync-rules.mdx
@@ -19,8 +19,8 @@ This SQL-like syntax is used when connecting to either Postgres, MongoDB or MySQ
 
 The [PowerSync Service](/architecture/powersync-service) uses these SQL-like queries to group data into "sync buckets" when replicating data to client devices.
 
-<Frame caption="Sync rules are configured per PowerSync instance.">
-  <img src="/images/usage-8.webp"/>
+<Frame caption="Sync rules are configured per PowerSync instance to enable partial sync.">
+  <img src="/images/usage/sync-rules/powersync-docs-diagram-sync-rules-001.png"/>
 </Frame>
 
 Functionality includes:
@@ -37,16 +37,16 @@ PowerSync replicates and transforms relevant data from the backend source databa
 
 Data from this step is persisted in separate sync buckets on the PowerSync Service. Data is incrementally updated so that sync buckets always contain current state data as well as a full history of changes.
 
-<Frame caption="Diagram showing how data is replicated from the source database into sync buckets.">
-  <img src="/images/usage-9.webp"/>
+<Frame caption="Data is replicated from the source database into sync buckets.">
+  <img src="/images/usage/sync-rules/powersync-docs-diagram-sync-rules-002.png"/>
 </Frame>
 
 ## Client Database Hydration
 
 PowerSync asynchronously hydrates local SQLite databases embedded in the PowerSync Client SDK based on data in sync buckets.
 
 <Frame caption="Data flow showing sync buckets which are created based on sync rules.">
-  <img src="/images/usage-10.webp"/>
+  <img src="/images/usage/sync-rules/powersync-docs-diagram-sync-rules-003.png"/>
 </Frame>