Merge pull request #108 from sqlitecloud/jacob/update-architecture

Architecture update and clean up

Author: TizianoT

sqlite-cloud/platform/scaling.mdx _architecture.mdxsqlite-cloud/platform/scaling.mdx renamed to _architecture.mdx

@@ -1,11 +1,13 @@
----
-title: Scaling
-description: How to scale your SQLite Cloud cluster.
-category: platform
-status: publish
-slug: scaling
----
 
+
+## Architecture
+SQLite Cloud uses the [Raft](https://raft.github.io) consensus algorithm to distribute your data changes across a cluster of computing systems, ensuring that each node in the cluster agrees upon the same series of state transitions. Raft implements consensus with a leader approach.
+
+SQLite Cloud is written in ANSI C and GO, and it works on most POSIX systems (Linux, *BSD, Mac OS X) and Windows. 
+
+SQLite Cloud supports all the SQLite features without any limitations, including ACID compliance and non-deterministic SQL statements.
+
+## Scaling your cluster
 SQLite Cloud leverages a customized Raft algorithm to maintain a robust and highly available database cluster. Here’s an essential guide on the node types within SQLite Cloud and strategic tips for scaling your cluster effectively.
 
 ## Overview of Node types

sqlite-cloud/_nav.ts

@@ -2,9 +2,9 @@ import type { SidebarNavStruct } from "@docs-website/types/sidebar-navigation";
 
 const sidebarNav: SidebarNavStruct = [
 	{ title: "", type: "primary" },
-	{ title: "Getting Started", type: "secondary", icon: "docs-star" },
-	{ title: "Introduction", href: "/docs/sqlite-cloud", type: "inner", level: 0 }, // should be index page for /docs and highlight "introduction" in nav
-	{ title: "Fundamentals", type: "inner", level: 0 },
+	{ title: "Introduction", type: "secondary", icon: "docs-star" },
+	{ title: "Overview", href: "/docs/sqlite-cloud", type: "inner", level: 0 },
+	{ title: "Getting Started", type: "inner", level: 0 },
 	{ title: "Connecting", filePath: "connect-cluster", type: "inner", level: 1 },
 	{ title: "Creating a database", filePath: "create-database", type: "inner", level: 1 },
 	{ title: "Writing data", filePath: "write-data", type: "inner", level: 1 },
@@ -26,7 +26,7 @@ const sidebarNav: SidebarNavStruct = [
 	{ title: "Integrations", type: "inner", level: 0 },
 	{ title: "Knex.js", filePath: "knex-integration", type: "inner", level: 1 },
 
-	{ title: "Platform", type: "secondary", icon: "docs-plat" },
+	{ title: "Platform",  type: "secondary", icon: "docs-plat" },
 	{ title: "Edge Functions", filePath: "edge-functions", type: "inner", level: 0 },
 	{ title: "Webhooks", filePath: "webhooks", type: "inner", level: 0 },
 	{ title: "Pub/Sub", filePath: "pub-sub", type: "inner", level: 0 },
@@ -39,9 +39,8 @@ const sidebarNav: SidebarNavStruct = [
 	{ title: "Weblite", filePath: "weblite", type: "inner", level: 0 },
 		// { title: "Storage", type: "inner", level: 0 },
 	// { title: "Partitioning", type: "inner", level: 0 },
-	{ title: "Settings", filePath: "settings", type: "inner", level: 0 },
 
-	{ title: "SDKs", type: "secondary", icon: "docs-sdk" },
+	{ title: "SDKs",  type: "secondary", icon: "docs-sdk" },
 	{ title: "C/C++", type: "inner", level: 0 },
 	{ title: "Introduction", type: "inner", filePath: "sdk-c-introduction", level: 1, },
 	{ title: 'Basic APIs', type: "inner", level: 1 },
@@ -177,7 +176,7 @@ const sidebarNav: SidebarNavStruct = [
 	{ title: "Swift", type: "inner", level: 0 },
 	{ title: 'Introduction', type: "inner", filePath: "sdk-swift-introduction", level: 1 },
 
-	{ title: "Reference", type: "secondary", icon: "docs-ref" },
+	{ title: "Reference",  type: "secondary", icon: "docs-ref" },
 	{ title: "Server-side Commands", type: "inner", level: 0 },
 	{ title: "Introduction", filePath: "server-side-commands", type: "inner", level: 1 },
 	{ title: "API Keys", filePath: "api-key-commands", type: "inner", level: 1 },

sqlite-cloud/connect-cluster.mdx

@@ -8,10 +8,7 @@ slug: connect-cluster
 
 SQLite databases in SQLite Cloud are distributed across a cluster of nodes. Each cluster comes with a multi-region load balancer that routes traffic to the nearest appropriate node.
 
-For this reason, we strongly recommend connecting to your cluster via your project connection string. To retrieve your project connection string, navigate to the **Nodes** page and click on any node. 
-{/* ![Project connection string modal](@docs-website-assets/connect-cluster-1.png) */}
-
-Copy the connection string and use it with a client library to connect to your cluster.
+Click "Connect" in the bottom left-hand corner of your dashboard to get your connection string to use with a SQLite Cloud client library.
 
 ## Connecting with JavaScript
 Here's an example of how you can connect to your cluster using the `@sqlitecloud/drivers` JavaScript client library:
@@ -63,4 +60,5 @@ conn.close()
 ```
 
 ## Next Steps
+- [Creating a database](/docs/create-database)
 - [Writing data](/docs/write-data)

sqlite-cloud/create-database.mdx

@@ -6,13 +6,25 @@ status: publish
 slug: create-database
 ---
 
-SQLite Cloud allows you to import existing SQLite Databases, or create a new database in SQLite Cloud by importing an existing SQLite database, or using the SQLite Cloud UI, API, or client libraries.
+You can import an existing SQLite databases, or create new databases using the SQLite Cloud UI, API, or client libraries.
 
-## Importing an existing SQLite database
-SQLite Cloud allows you to import existing SQLite databases into the platform. 
+## Uploading an existing SQLite Database
+### Via HTTP API
+You can upload an existing SQLite database to your cluster using the SQLite Cloud UI or the Weblite API.
 
-Note that you can download, modify, and re-upload the database file at any time. You can also upload encrypted SQLite databases if you used the official SEE SQLite encryption extension.
+To upload a local SQLite database via weblite, make a POST request to the `/v2/weblite/<database-name>.sqlite` endpoint.
 
+```bash
+curl -X 'POST' \
+  'https://<your-project-id>.sqlite.cloud:8090/v2/weblite/<database-name>.sqlite' \
+  -H 'accept: application/json' \
+  -H 'Authorization: Bearer sqlitecloud://<your-project-id>.sqlite.cloud:8860?apikey=<your-api-key>' \
+  -d ''
+```
+
+To upload a local SQLite database via the SQLite Cloud UI, navigate to the Database tab in the left-hand navigation. Click the "Upload Database" button and select your local SQLite database.
+
+### Via Dashboard UI
 To import a database from the UI, navigate to the Databases tab and click the "Upload Database" button.
 ![Dashbord Upload Database](@docs-website-assets/introduction/dashboard_upload_db.png)
 
@@ -27,7 +39,7 @@ To create a new database from the SQLite Cloud UI, navigate to the Databases tab
 The default encoding is set to UTF-8, and the default page size is 4096KB.
 
 ### From the API
-To create a new database or upload an existing database via [Weblite](#), our REST API, you can make a request with the following parameters:
+To create a new database or upload an existing database via [Weblite](/docs/weblite), our REST API, you can make a request with the following parameters:
 ```bash
 curl -X 'POST' \
   'https://<your-project-id>.sqlite.cloud:8090/v2/weblite/<database-name>.sqlite' \
@@ -37,17 +49,32 @@ curl -X 'POST' \
 ```
 
 ### From client libraries
-To create a new database from a client library, use the CREATE DATABASE command. 
+To create a new database from a client library, connect to your cluster using a connection string without a specified database.
+
+Then, use the CREATE DATABASE command to create a new database. 
+
+To start using the database within the connection, you can use the `USE DATABASE` command.
 
 ```javascript
 import { Database } from '@sqlitecloud/drivers';
-
+// note that no database name is specified in the connection string path
 const db = new Database('sqlitecloud://<your-project-id>.sqlite.cloud:<your-host-port>?apikey=<your-api-key>')
 
 const createDatabase = async () => await db.sql`CREATE DATABASE <database-name>;`;
 
 createDatabase().then((res) => console.log(res));
 
 // "OK"
+
+db.exec('USE DATABASE <database-name>;')
+
+// now you can use the database
+const fetchAlbums = async () => await db.exec`SELECT * FROM albums;`;
+
+fetchAlbums().then((albums) => console.log(albums));
+
+// [{ Title: 'For Those About To Rock We Salute You', ... }, ...]
 ```
 
+## Next Steps
+- [Writing data](/docs/write-data)

sqlite-cloud/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: Introduction to SQLite Cloud
+title: Getting Started with SQLite Cloud
 description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine.
 category: getting-started
 status: publish
@@ -8,27 +8,22 @@ status: publish
 ## Overview
 **SQLite Cloud** is a managed, distributed relational database system built on top of the SQLite database engine. 
 
-It has been designed from the ground up to ensure strong consistency across all nodes in a cluster while simultaneously managing the technical aspects of scaling, security, and data distribution. This ensures that you can focus on your core tasks while relying on **SQLite Cloud** to handle the complexities of managing your databases.
+It has been designed from the ground up to ensure strong consistency across all nodes in a cluster while simultaneously managing the technical aspects of scaling, security, and data distribution. This ensures that you can focus on your core tasks while relying on SQLite Cloud to handle the complexities of managing your databases.
 
-**SQLite Cloud** is written in ANSI C and GO, and it works on most POSIX systems like Linux, *BSD, and Mac OS X (Windows is supported too). You can use **SQLite Cloud** from the most popular programming languages or its REST API.
+SQLite Cloud is built on the open source SQLite engine, ensuring complete feature parity. You get all of SQLite's core strengths: ACID compliance, support for complex SQL operations, and compatibility with the rich SQLite extension ecosystem.
 
----
-
-## Architecture
-
-**SQLite Cloud** uses the [Raft](https://raft.github.io) consensus algorithm to distribute your data changes across a cluster of computing systems, ensuring that each node in the cluster agrees upon the same series of state transitions. Raft implements consensus with a leader approach.
+You can access SQLite Cloud from the most popular programming languages or its REST API. 
 
-**SQLite Cloud** supports all the SQLite features without any limitations. It is fully ACID compliant, supports non-deterministic SQL statements, and guarantees strong consistency across all your cluster nodes. This ensures that data read from any node in the system returns the most up-to-date version of the data that has been committed.
+Like SQLite, each database in SQLite Cloud is a separate file, giving you flexible deployment options:
 
-In a distributed database system, where data is distributed across multiple nodes, ensuring strong consistency can be challenging due to the potential for network delays, node failures, and concurrent transactions. Maintaining strong consistency is crucial for ensuring that the system behaves as expected and that applications built on top of the system can rely on the accuracy and integrity of the data.
+* Create separate databases for each customer in a multi-tenant application
+* Share a single database among multiple users with built-in access controls
+* Mix both approaches based on your application's needs
 
-## Features
-SQLite Cloud provides a comprehensive suite of tools for building realtime, local-first applications.
-* **Local Sync**: Query your local SQLite database and synchronize with the cloud and across devices in real-time (**In development**).
-* **Offline-first**: Resolve conflicts between devices and the cloud with CRDTs (**In development**).
-* **[Webhooks](/docs/webhooks)**: Send changes to your database to external endpoints, or use to trigger edge functions via HTTP, Websockets, or on database events like INSERT, UPDATE, and DELETE.
-* **[Edge Functions](/docs/edge-functions)**: Run serverless functions on the same node that stores your data for low-latency operations. Trigger with webhooks or on database operations.
+### Features
+SQLite Cloud provides a comprehensive suite of tools for building realtime, local-first, edge AI applications.
+* **[Webhooks](/docs/webhooks)**: Trigger edge functions or send change payloads via HTTP, Websockets, or on database events like INSERT, UPDATE, and DELETE.
+* **[Edge Functions](/docs/edge-functions)**: Run serverless functions on the same nodes that store your data for lightning-fast data access.
 * **[Pub/Sub](/docs/pub-sub)**: Subscribe to changes in your database to replicate data, power notifications, and build multiplayer experiences.
-* **Weblite**: Autogenerated REST APIs to interact with your database and edge functions.
-* **[Query Analyzer](/docs/analyzer)**: Receive optimization recommendations for your queries to improve performance.
-* **Multi-region Load Balancer**: Connect to SQLite Cloud from anywhere in the world and SQLite Cloud automatically routes traffic to the nearest node for optimal performance.
+* **[Weblite](/docs/weblite)**: Autogenerated REST APIs to interact with the SQLite Cloud platform.
+* **[Query Analyzer](/docs/analyzer)**: Receive optimization recommendations for your queries to improve performance.

sqlite-cloud/introduction.mdx

@@ -0,0 +1,35 @@
+---
+title: Introduction to SQLite Cloud
+description: SQLite Cloud is a distributed relational database system built on top of the SQLite database engine.
+category: getting-started
+status: publish
+slug: introduction
+---
+
+## Overview
+**SQLite Cloud** is a managed, distributed relational database system built on top of the SQLite database engine. 
+
+It has been designed from the ground up to ensure strong consistency across all nodes in a cluster while simultaneously managing the technical aspects of scaling, security, and data distribution. This ensures that you can focus on your core tasks while relying on **SQLite Cloud** to handle the complexities of managing your databases.
+
+**SQLite Cloud** is written in ANSI C and GO, and it works on most POSIX systems like Linux, *BSD, and Mac OS X (Windows is supported too). You can use **SQLite Cloud** from the most popular programming languages or its REST API.
+
+---
+
+## Architecture
+
+**SQLite Cloud** uses the [Raft](https://raft.github.io) consensus algorithm to distribute your data changes across a cluster of computing systems, ensuring that each node in the cluster agrees upon the same series of state transitions. Raft implements consensus with a leader approach.
+
+**SQLite Cloud** supports all the SQLite features without any limitations. It is fully ACID compliant, supports non-deterministic SQL statements, and guarantees strong consistency across all your cluster nodes. This ensures that data read from any node in the system returns the most up-to-date version of the data that has been committed.
+
+In a distributed database system, where data is distributed across multiple nodes, ensuring strong consistency can be challenging due to the potential for network delays, node failures, and concurrent transactions. Maintaining strong consistency is crucial for ensuring that the system behaves as expected and that applications built on top of the system can rely on the accuracy and integrity of the data.
+
+## Features
+SQLite Cloud provides a comprehensive suite of tools for building realtime, local-first applications.
+* **Local Sync**: Query your local SQLite database and synchronize with the cloud and across devices in real-time (**In development**).
+* **Offline-first**: Resolve conflicts between devices and the cloud with CRDTs (**In development**).
+* **[Webhooks](/docs/webhooks)**: Send changes to your database to external endpoints, or use to trigger edge functions via HTTP, Websockets, or on database events like INSERT, UPDATE, and DELETE.
+* **[Edge Functions](/docs/edge-functions)**: Run serverless functions on the same node that stores your data for low-latency operations. Trigger with webhooks or on database operations.
+* **[Pub/Sub](/docs/pub-sub)**: Subscribe to changes in your database to replicate data, power notifications, and build multiplayer experiences.
+* **Weblite**: Autogenerated REST APIs to interact with your database and edge functions.
+* **[Query Analyzer](/docs/analyzer)**: Receive optimization recommendations for your queries to improve performance.
+* **Multi-region Load Balancer**: Connect to SQLite Cloud from anywhere in the world and SQLite Cloud automatically routes traffic to the nearest node for optimal performance.

sqlite-cloud/platform/backups.mdx

@@ -7,7 +7,7 @@ slug: backups
 ---
 
 ## Overview
-Backups provide a robust solution for mitigating data loss and resolving data corruption issues. 
+Backups provide a robust solution for mitigating data loss and resolving data corruption issues. Backups are available for databases in all [Pro and Scale](https://www.sqlitecloud.io/pricing) projects.
 
 SQLite Cloud creates a full snapshot backup of your data once a day, and stores incremental changes once per second, on commodity object storage.
 

sqlite-cloud/platform/edge-functions.mdx

@@ -6,7 +6,7 @@ status: publish
 slug: edge-functions
 ---
 
-Edge Functions are server-side functions that run directly within your database environment. Edge functions in SQLite Cloud ensure maximum performance and minimal latency by running functions on the same server as your database.
+Edge functions let you define custom logic to run on the same nodes as your database files for ultra-fast performance.
 
 You can write edge functions directly in the SQLite Cloud dashboard using JavaScript, TypeScript, or SQL. Importing modules is not currently supported.
 

sqlite-cloud/platform/index.mdx

@@ -0,0 +1,83 @@
+---
+title: Platform 
+description: Index page for platform section
+category: platform
+status: publish
+icon: docs-plat
+slug: platform
+---
+import IndexPage from "@docs-website-components/Docs/IndexPage.astro"
+
+export const introduction = "SQLite Cloud is a distributed relational database system built on top of the SQLite database engine. It has been specifically designed from the ground up to ensure the strong consistency of your data across all nodes in a cluster while simultaneously managing the technical aspects of scaling, security, and data distribution."
+
+export const sections = [
+    {
+        icon: "puzzle",
+        title: "Edge Functions",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/edge-functions",
+    },
+    {
+        icon: "puzzle",
+        title: "Webhooks",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/webhooks",
+    },
+    {
+        icon: "puzzle",
+        title: "Pub/Sub",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/pub-sub",
+    },
+    {
+        icon: "puzzle",
+        title: "Vector",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/vector",
+    },
+    {
+        icon: "puzzle",
+        title: "Scaling",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/scaling",
+    },
+    {
+        icon: "puzzle",
+        title: "Security and Access Control",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/security",
+    },
+    {
+        icon: "puzzle",
+        title: "Backups",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/backups",
+    },
+    {
+        icon: "puzzle",
+        title: "Query Analyzer",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/analyzer",
+    },
+    {
+        icon: "puzzle",
+        title: "Extensions",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/extensions",
+    },
+    {
+        icon: "puzzle",
+        title: "Weblite",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/weblite",
+    },
+    {
+        icon: "puzzle",
+        title: "Settings",
+        description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+        href: "/docs/settings",
+    },
+]
+
+
+<IndexPage introduction={introduction} sections={sections} />