From cc16dc1f8b11c370ae20dd46169e1e0a1440ec1f Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 24 Jun 2026 09:20:50 +0100 Subject: [PATCH 1/5] docs: Realign How it works around the hot-reload dev loop (#566) --- docs/04-get-started/03-how-it-works.md | 82 +++++++++++--------------- 1 file changed, 33 insertions(+), 49 deletions(-) diff --git a/docs/04-get-started/03-how-it-works.md b/docs/04-get-started/03-how-it-works.md index 7f4aa6a2..a9e18efc 100644 --- a/docs/04-get-started/03-how-it-works.md +++ b/docs/04-get-started/03-how-it-works.md @@ -2,83 +2,67 @@ sidebar_label: How it works sidebar_class_name: sidebar-icon-overview slug: /how-it-works -description: "Understand Serverpod's architecture: the three-package layout, the code generator, and the request lifecycle that gives you full-stack type safety." +description: "Understand your day with Serverpod: the save-and-hot-reload dev loop, the three-package layout and code generator, and full-stack type safety." --- # How Serverpod works -Serverpod is built around three Dart packages and a code generator, which bridges the gap between your server-side logic, your database, and your Flutter app. Together, they give you full-stack type safety from your database to your Flutter app. +With Serverpod you write Dart on both sides of your app and run one command to see your changes immediately. Edit a file, hit save, and your running server, your Flutter app, and the generated code that connects them update together. No manual rebuilds or restarts, no Docker to wire up, and no API code to write by hand. -## Project structure +Serverpod is a full backend: the database, authentication, file uploads, caching, and real-time are built in, so you build features instead of wiring together separate services. Underneath, a Serverpod project is a single workspace of Dart packages, and a code generator keeps the types shared between your server and app in sync. -When you run `serverpod create`, it produces three Dart packages in a single workspace: +## What you build + +When you run `serverpod create`, you get one workspace with three Dart packages: ```text my_project/ -├── my_project_server/ # Your server-side code -├── my_project_client/ # Auto-generated. Never edit by hand. +├── my_project_server/ # Your backend code. +├── my_project_client/ # Generated. Never edit by hand. └── my_project_flutter/ # Your Flutter app. ``` -The `_server` package holds your backend code, while the `_client` package acts as a bridge, providing the Flutter app with a typed API to call the server. - -Because the client package is auto-generated from the server code, there is no need to write serialization code, HTTP calls, or API contracts. - -## Code generation +You write your backend in the `_server` package: [endpoint methods](../concepts/working-with-endpoints) that your app calls, and [model files](../concepts/models) (`.spy.yaml`) that define your data. From those, Serverpod's code generator produces the `_client` package, a typed Dart API for your app, along with the serialization and database classes on the server. You never write serialization, HTTP calls, or API contracts. -Code generation cuts boilerplate and keeps types in sync between server and app. Serverpod watches your `_server` package as you edit and runs the generator automatically. +That makes a call to the server look like a local method call: -The generator reads two kinds of source files: - -- **Model files (`.spy.yaml`)** defining your data classes. -- **Endpoint classes** defining your server's API. +```dart +final greeting = await client.example.hello('World'); +``` -From these files, Serverpod generates: +The generated client handles the request, the response, and the JSON in between. Every endpoint method also receives a [`Session`](../concepts/sessions), the context for that one call, with access to the database, cache, signed-in user, and logging. -- **A typed client** in the `_client` package, allowing your Flutter app to call the backend with full type-safety. -- **Serialization and ORM classes** in the `_server` package, for database access and communication. +Most calls follow this request-and-response shape. For live updates, Serverpod also has [streaming endpoints](../concepts/streams) that keep a connection open so the server and app can push data to each other. -## Calling the backend +## The dev loop -Thanks to the generated client, calling a server endpoint from your Flutter app feels like a local method call. You do not need to write any networking or serialization code. +Day to day, you run one command: -```dart -final result = await client.greeting.hello('World'); +```bash +$ serverpod start ``` -This example calls the `hello` method on the `greeting` endpoint. The generated client handles the JSON serialization, HTTP request, and response deserialization automatically. - -## Request lifecycle +This starts your server, launches your Flutter app, and watches your code. When you save a change, Serverpod hot reloads the server, regenerates the client, and reloads your app. When your models change, it applies migrations to keep your database in sync. You stay in one terminal and see each change right away. -When your Flutter app calls a server method, the generated client serializes the request and sends it to the server. Serverpod uses a protocol similar to JSON-RPC, which makes remote method calls feel like local function calls instead of traditional REST requests. +By default there is no Docker to set up. Serverpod runs an embedded Postgres for you, managed by the server. If you would rather run Postgres or other services in Docker, opt in with `serverpod start --docker`. -The diagram below shows the journey of a request: +## An AI-assisted workflow -```mermaid -sequenceDiagram - participant App as Flutter app - participant Client as Generated client - participant Server as Serverpod server - participant Endpoint as Your endpoint - - App->>Client: client.endpoint.method(args) - Client->>Server: HTTP request (JSON) - Server->>Endpoint: method(session, args) - Endpoint-->>Server: result - Server-->>Client: HTTP response (JSON) - Client-->>App: typed Dart object -``` +If you build with AI tools, Serverpod supports that too. When you create a project, it can scaffold agent skills for your editor (Claude, Cursor, and VS Code), and `serverpod start` runs an MCP server that lets those tools work with your running project. This path is entirely optional, and the traditional workflow above is unchanged if you do not use it. -### Real-time streaming +## Choices that shape your project -Regular endpoint methods follow the request/response lifecycle above. For real-time use cases like live updates, collaborative features, and multiplayer, Serverpod also supports [streaming endpoints](../06-concepts/15-streams.md), which keep a WebSocket connection open and let server and client push data to each other continuously. +The `serverpod create` command lets you tailor the project it generates. You choose: -### Session +- **Project type.** A full server, or a reusable module shared across servers. +- **Database and caching.** Postgres or SQLite, plus optional Redis for caching and cross-server messaging. +- **Authentication.** Built-in email and social sign-in, one of Serverpod's optional [modules](../concepts/modules). +- **Web server.** Optionally serve web pages and your Flutter web build alongside your API. -The `Session` parameter that every endpoint method receives is the context for that single request. It gives access to the database, cache, signed-in user, and logging, all available only while the request runs. Each call gets its own `Session`. +## Why it works -## Type safety across the stack +Type safety runs from your database to your Flutter app because your model files are the single source of truth. When you generate code, the same Dart class is used in database queries, server logic, and your app. Rename a field and regenerate, and the Dart compiler points you at every place in the server and the app that needs updating. A whole category of client-server bugs (mismatched field names, wrong types, forgotten null checks after an API change) becomes compile errors you fix before you ship. This safety net matters all the more when AI tools are writing some of that code for you. -Type safety across the entire stack, from the database to your Flutter app, is guaranteed because Serverpod's model files (`.spy.yaml`) are the single source of truth. When code is generated, the same Dart class is used in database queries, server logic, and your Flutter app. +## Next steps -This eliminates a whole category of bugs common in traditional client-server development, such as mismatched field names, incorrect types, or forgotten null checks after an API change. If you rename a field in a model file and regenerate, the Dart compiler immediately tells you every place in both the server and the app that needs updating. +When you are ready to ship, see [Deploy to Serverpod Cloud](../deployments/deploy-to-serverpod-cloud) to take your app to production. From bcd62bdc89f895bb7a343137961c6a8de88617a1 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 24 Jun 2026 09:54:30 +0100 Subject: [PATCH 2/5] docs: Fix broken Serverpod Cloud deploy link in How it works --- docs/04-get-started/03-how-it-works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-get-started/03-how-it-works.md b/docs/04-get-started/03-how-it-works.md index a9e18efc..84568009 100644 --- a/docs/04-get-started/03-how-it-works.md +++ b/docs/04-get-started/03-how-it-works.md @@ -65,4 +65,4 @@ Type safety runs from your database to your Flutter app because your model files ## Next steps -When you are ready to ship, see [Deploy to Serverpod Cloud](../deployments/deploy-to-serverpod-cloud) to take your app to production. +When you are ready to ship, see [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) to take your app to production. From 756d4356c639a6d9b32678d27573f79b62e6978f Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Wed, 24 Jun 2026 10:00:01 +0100 Subject: [PATCH 3/5] docs: Point How it works next steps to the tutorial --- docs/04-get-started/03-how-it-works.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-get-started/03-how-it-works.md b/docs/04-get-started/03-how-it-works.md index 84568009..97c4f40c 100644 --- a/docs/04-get-started/03-how-it-works.md +++ b/docs/04-get-started/03-how-it-works.md @@ -65,4 +65,4 @@ Type safety runs from your database to your Flutter app because your model files ## Next steps -When you are ready to ship, see [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) to take your app to production. +Ready to build something? Follow [Build your first app](../05-build-your-first-app/01-creating-endpoints.md) to create your first endpoint and call it from Flutter. From f0fc24d6bfcfbedb72ba62a36bdb390a6fb272e7 Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Thu, 25 Jun 2026 10:45:41 +0100 Subject: [PATCH 4/5] docs: Reframe How it works as a quickstart for working with Serverpod --- docs/04-get-started/03-how-it-works.md | 103 +++++++++++++++++++------ 1 file changed, 78 insertions(+), 25 deletions(-) diff --git a/docs/04-get-started/03-how-it-works.md b/docs/04-get-started/03-how-it-works.md index 97c4f40c..7e18dea7 100644 --- a/docs/04-get-started/03-how-it-works.md +++ b/docs/04-get-started/03-how-it-works.md @@ -2,18 +2,26 @@ sidebar_label: How it works sidebar_class_name: sidebar-icon-overview slug: /how-it-works -description: "Understand your day with Serverpod: the save-and-hot-reload dev loop, the three-package layout and code generator, and full-stack type safety." +description: 'The fast way to start building with Serverpod: write endpoints, call them from Flutter, define data models, and see changes with one-command hot reload.' --- # How Serverpod works With Serverpod you write Dart on both sides of your app and run one command to see your changes immediately. Edit a file, hit save, and your running server, your Flutter app, and the generated code that connects them update together. No manual rebuilds or restarts, no Docker to wire up, and no API code to write by hand. -Serverpod is a full backend: the database, authentication, file uploads, caching, and real-time are built in, so you build features instead of wiring together separate services. Underneath, a Serverpod project is a single workspace of Dart packages, and a code generator keeps the types shared between your server and app in sync. +Serverpod is a full backend: the database, authentication, file uploads, caching, real-time, scheduling, and logging are built in, so you build features instead of wiring together separate services. A project is a single workspace of Dart packages, and a code generator keeps the types shared between your server and app in sync, so a renamed field or a wrong type is a compile error rather than a runtime surprise. -## What you build +## Create your project -When you run `serverpod create`, you get one workspace with three Dart packages: +A Serverpod project starts with the `serverpod create` command, which walks you through a few choices that shape what it generates: + +- **Project type:** A full server, or a reusable module shared across servers. +- **Database and caching:** Postgres or SQLite, plus optional Redis for caching and cross-server messaging. +- **Authentication:** Built-in email and social sign-in, one of Serverpod's optional [modules](../concepts/modules). +- **Web server:** Optionally serve web pages and your Flutter web build alongside your API. +- **AI agent (optional):** The coding agent you build with (Claude, Cursor, or VS Code), set up with agent skills. + +The result is one workspace with three Dart packages: ```text my_project/ @@ -22,47 +30,92 @@ my_project/ └── my_project_flutter/ # Your Flutter app. ``` -You write your backend in the `_server` package: [endpoint methods](../concepts/working-with-endpoints) that your app calls, and [model files](../concepts/models) (`.spy.yaml`) that define your data. From those, Serverpod's code generator produces the `_client` package, a typed Dart API for your app, along with the serialization and database classes on the server. You never write serialization, HTTP calls, or API contracts. +You write two kinds of things in the `_server` package: endpoints that your app calls, and models that define your data. Serverpod's code generator turns them into the `_client` package, a typed Dart API for your app, along with the serialization and database code on the server. You never write serialization, HTTP calls, or API contracts. + +## Run your project + +You run the whole project with one command: + +```bash +$ serverpod start +``` + +This starts your server, launches your Flutter app, and watches your code. When you save a change, Serverpod regenerates the client, hot reloads the server, and reloads your app, so you see each change right away. + +:::tip + +Start your project before you begin building. With `serverpod start` already running, every change after that, whether you make it or an agent does, is caught and reloaded as you go. + +::: + +## Write an endpoint + +In Serverpod, endpoints are the entry points your app calls to run code on the server. You define one as a class that extends `Endpoint`, with async methods that each take a [`Session`](../concepts/sessions) as their first argument and return a typed `Future`: + +```dart +class ExampleEndpoint extends Endpoint { + Future hello(Session session, String name) async { + return 'Hello $name'; + } +} +``` + +The `Session` is the context for that one call, with access to the database, cache, signed-in user, and logging. Parameters and return types can be the built-in types (`bool`, `int`, `double`, `String`, `DateTime`, `Duration`, `Uri`, `UuidValue`, `BigInt`, `ByteData`), a `List`, `Map`, `Set`, or `Record` of those, or any model you define. See [Working with endpoints](../concepts/working-with-endpoints) for the full list. + +## Call it from your app -That makes a call to the server look like a local method call: +On the app side, the generated client turns each endpoint method into what looks like a local call: ```dart final greeting = await client.example.hello('World'); ``` -The generated client handles the request, the response, and the JSON in between. Every endpoint method also receives a [`Session`](../concepts/sessions), the context for that one call, with access to the database, cache, signed-in user, and logging. +The client handles the request, the response, and the JSON in between. Most calls follow this request-and-response shape. For live updates, Serverpod also has [streaming endpoints](../concepts/streams) that keep a connection open so the server and app can push data to each other. -Most calls follow this request-and-response shape. For live updates, Serverpod also has [streaming endpoints](../concepts/streams) that keep a connection open so the server and app can push data to each other. +## Define your data models -## The dev loop +Models are the data your app and server pass back and forth, the objects your endpoints take and return. You define them in `.spy.yaml` files, each naming a class and listing its fields: -Day to day, you run one command: +```yaml +class: Company +fields: + name: String + foundedDate: DateTime? +``` -```bash -$ serverpod start +When you generate code, this becomes a `Company` Dart class shared by the server and your app, so the same type flows from your endpoints into your Flutter widgets. Fields support the same types as endpoint methods, plus enums and nested models, and can be nullable. See [Working with models](../concepts/models) for the details. + +Add a `table` key to also store the model in a database table: + +```yaml +class: Company +table: company +fields: + name: String + foundedDate: DateTime? ``` -This starts your server, launches your Flutter app, and watches your code. When you save a change, Serverpod hot reloads the server, regenerates the client, and reloads your app. When your models change, it applies migrations to keep your database in sync. You stay in one terminal and see each change right away. +The generated `Company` class then gains a `db` field with type-safe methods for reading and writing rows, so you query the database in Dart instead of SQL. For example, insert a row and read it back: -By default there is no Docker to set up. Serverpod runs an embedded Postgres for you, managed by the server. If you would rather run Postgres or other services in Docker, opt in with `serverpod start --docker`. +```dart +final company = await Company.db.insertRow(session, Company(name: 'Serverpod')); +final stored = await Company.db.findById(session, company.id); +``` -## An AI-assisted workflow +These run on the same `session` your endpoint method receives. When you change a table model, press `M` in the `serverpod start` terminal to create a migration, then `A` to apply it. Pending migrations also apply on startup. -If you build with AI tools, Serverpod supports that too. When you create a project, it can scaffold agent skills for your editor (Claude, Cursor, and VS Code), and `serverpod start` runs an MCP server that lets those tools work with your running project. This path is entirely optional, and the traditional workflow above is unchanged if you do not use it. +That database runs without setup on your part: Serverpod manages an embedded Postgres for you, with no Docker to configure. If you would rather run Postgres or other services in Docker, opt in with `serverpod start --docker`. -## Choices that shape your project +See [Working with the database](../concepts/database/crud) for filters, relations, and transactions. -The `serverpod create` command lets you tailor the project it generates. You choose: +## Build with an AI agent -- **Project type.** A full server, or a reusable module shared across servers. -- **Database and caching.** Postgres or SQLite, plus optional Redis for caching and cross-server messaging. -- **Authentication.** Built-in email and social sign-in, one of Serverpod's optional [modules](../concepts/modules). -- **Web server.** Optionally serve web pages and your Flutter web build alongside your API. +Serverpod is built to work with AI coding agents. You pick your agent when you create the project, and Serverpod scaffolds skills that teach it how a Serverpod project fits together. While `serverpod start` runs, it exposes an MCP server that lets the agent work with your live project: write endpoints and models, manage the database, and reload the app as it goes. You describe the feature you want, and the agent builds it. -## Why it works +Your models stay the single source of truth, so when the agent renames a field or changes a type, the regenerated code turns the mismatch into a compile error rather than a runtime bug. -Type safety runs from your database to your Flutter app because your model files are the single source of truth. When you generate code, the same Dart class is used in database queries, server logic, and your app. Rename a field and regenerate, and the Dart compiler points you at every place in the server and the app that needs updating. A whole category of client-server bugs (mismatched field names, wrong types, forgotten null checks after an API change) becomes compile errors you fix before you ship. This safety net matters all the more when AI tools are writing some of that code for you. +This path is optional, and everything above works the same without it. For a guided walkthrough, see the [Quickstart](02-quickstart.md). ## Next steps -Ready to build something? Follow [Build your first app](../05-build-your-first-app/01-creating-endpoints.md) to create your first endpoint and call it from Flutter. +Ready to build something? Follow [Build your first app](../05-build-your-first-app/01-creating-endpoints.md) to create your first endpoint and call it from Flutter. When you are ready to ship, [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) takes your app to production. From 108d6d2e2750767cee382fb99afd694be0f171ed Mon Sep 17 00:00:00 2001 From: developerjamiu Date: Thu, 25 Jun 2026 12:19:41 +0100 Subject: [PATCH 5/5] docs: Address review feedback on How it works --- docs/04-get-started/03-how-it-works.md | 42 +++++++++++++------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/04-get-started/03-how-it-works.md b/docs/04-get-started/03-how-it-works.md index 7e18dea7..b62b94a4 100644 --- a/docs/04-get-started/03-how-it-works.md +++ b/docs/04-get-started/03-how-it-works.md @@ -2,35 +2,35 @@ sidebar_label: How it works sidebar_class_name: sidebar-icon-overview slug: /how-it-works -description: 'The fast way to start building with Serverpod: write endpoints, call them from Flutter, define data models, and see changes with one-command hot reload.' +description: 'Start building with Serverpod. Learn how to add endpoints, call them from Flutter, define data models, and work with hot reload across the backend and your app.' --- # How Serverpod works -With Serverpod you write Dart on both sides of your app and run one command to see your changes immediately. Edit a file, hit save, and your running server, your Flutter app, and the generated code that connects them update together. No manual rebuilds or restarts, no Docker to wire up, and no API code to write by hand. +With Serverpod, you write type-safe Dart on both your Flutter app and the backend. With hot reload, all the changes immediately take effect. Edit a file, hit save, and your running server, your Flutter app, your database, and the generated code that connects them update together. No manual rebuilds or restarts, no Docker to wire up, and no API code to write by hand. -Serverpod is a full backend: the database, authentication, file uploads, caching, real-time, scheduling, and logging are built in, so you build features instead of wiring together separate services. A project is a single workspace of Dart packages, and a code generator keeps the types shared between your server and app in sync, so a renamed field or a wrong type is a compile error rather than a runtime surprise. +Serverpod is a full backend. It manages your database, authentication, file uploads, caching, real-time communication, scheduling, and logging. You can focus on building features instead of wiring together separate services. A project is a single workspace of Dart packages, and a code generator keeps the types shared between your server and app in sync. If you rename a field or use an incorrect type, they will show up as compile-time errors rather than a surprise when you run the app. ## Create your project A Serverpod project starts with the `serverpod create` command, which walks you through a few choices that shape what it generates: -- **Project type:** A full server, or a reusable module shared across servers. -- **Database and caching:** Postgres or SQLite, plus optional Redis for caching and cross-server messaging. -- **Authentication:** Built-in email and social sign-in, one of Serverpod's optional [modules](../concepts/modules). -- **Web server:** Optionally serve web pages and your Flutter web build alongside your API. -- **AI agent (optional):** The coding agent you build with (Claude, Cursor, or VS Code), set up with agent skills. +- **Project type:** A full server, or a reusable [module](../concepts/modules) shared across servers. +- **Database and caching:** Add a Postgres database and Redis (for pub/sub and caching). +- **Authentication:** Built-in email and social sign-ins. +- **Web server:** Optionally serve web pages and your Flutter web app alongside your API. +- **AI agent / Code editor (optional):** The coding agent you build with (Claude, Cursor, or VS Code), set up with agent skills. The result is one workspace with three Dart packages: ```text my_project/ ├── my_project_server/ # Your backend code. -├── my_project_client/ # Generated. Never edit by hand. +├── my_project_client/ # Generated client code used by the app. └── my_project_flutter/ # Your Flutter app. ``` -You write two kinds of things in the `_server` package: endpoints that your app calls, and models that define your data. Serverpod's code generator turns them into the `_client` package, a typed Dart API for your app, along with the serialization and database code on the server. You never write serialization, HTTP calls, or API contracts. +In the `_server` package you add your endpoints and data models. Serverpod's code generator generates code on the server and in the client package. You get a type-safe Dart API for your app, along with the serialization and database code on the server. You never write serialization, HTTP calls, or API contracts. ## Run your project @@ -40,11 +40,11 @@ You run the whole project with one command: $ serverpod start ``` -This starts your server, launches your Flutter app, and watches your code. When you save a change, Serverpod regenerates the client, hot reloads the server, and reloads your app, so you see each change right away. +This starts your server, launches your Flutter app, and watches your code. When you make a change, Serverpod instantly regenerates the client, hot reloads the server, and reloads your app. :::tip -Start your project before you begin building. With `serverpod start` already running, every change after that, whether you make it or an agent does, is caught and reloaded as you go. +Start your project before you begin building. With `serverpod start` already running, every change after that, whether you make it yourself or an agent does it, is reloaded as you go. ::: @@ -60,11 +60,11 @@ class ExampleEndpoint extends Endpoint { } ``` -The `Session` is the context for that one call, with access to the database, cache, signed-in user, and logging. Parameters and return types can be the built-in types (`bool`, `int`, `double`, `String`, `DateTime`, `Duration`, `Uri`, `UuidValue`, `BigInt`, `ByteData`), a `List`, `Map`, `Set`, or `Record` of those, or any model you define. See [Working with endpoints](../concepts/working-with-endpoints) for the full list. +The `Session` is the context for that one call, with access to the database, cache, signed-in user, and logging. Parameters and return types can be the built-in types (`bool`, `int`, `double`, `String`, `DateTime`, `Duration`, `Uri`, `UuidValue`, `BigInt`, `ByteData`), a `List`, `Map`, `Set`, or `Record` of those, or any data model you define. See [Working with endpoints](../concepts/working-with-endpoints) for more information. ## Call it from your app -On the app side, the generated client turns each endpoint method into what looks like a local call: +On the app side, the generated client turns each endpoint method into what looks like a local method: ```dart final greeting = await client.example.hello('World'); @@ -74,7 +74,7 @@ The client handles the request, the response, and the JSON in between. Most call ## Define your data models -Models are the data your app and server pass back and forth, the objects your endpoints take and return. You define them in `.spy.yaml` files, each naming a class and listing its fields: +Models are the data classes your app and server pass back and forth, the objects your endpoints take and return. You define them in `.spy.yaml` files, each naming a class and listing its fields: ```yaml class: Company @@ -104,18 +104,18 @@ final stored = await Company.db.findById(session, company.id); These run on the same `session` your endpoint method receives. When you change a table model, press `M` in the `serverpod start` terminal to create a migration, then `A` to apply it. Pending migrations also apply on startup. -That database runs without setup on your part: Serverpod manages an embedded Postgres for you, with no Docker to configure. If you would rather run Postgres or other services in Docker, opt in with `serverpod start --docker`. +That database runs without setup on your part: Serverpod manages an embedded Postgres for you, with no Docker to configure. If you would rather manage Postgres yourself, you can change the configuration in the server's `config` directory. -See [Working with the database](../concepts/database/crud) for filters, relations, and transactions. +See [Working with the database](../concepts/database/crud) for building queries, relations, and transactions. ## Build with an AI agent -Serverpod is built to work with AI coding agents. You pick your agent when you create the project, and Serverpod scaffolds skills that teach it how a Serverpod project fits together. While `serverpod start` runs, it exposes an MCP server that lets the agent work with your live project: write endpoints and models, manage the database, and reload the app as it goes. You describe the feature you want, and the agent builds it. +Serverpod is built to work with AI coding agents. You pick your agent when you create the project, and Serverpod installs skills that teach it how a Serverpod project fits together. While `serverpod start` runs, it exposes an MCP server that lets the agent work with your live project. It can write endpoints and models, manage the database, and reload the app as it goes. You describe the feature you want, and the agent builds it. -Your models stay the single source of truth, so when the agent renames a field or changes a type, the regenerated code turns the mismatch into a compile error rather than a runtime bug. +Your data models and endpoint methods are the single source of truth. When the agent renames a field or changes its type, the regenerated code treats the mismatch as a compile-time error rather than a runtime bug. -This path is optional, and everything above works the same without it. For a guided walkthrough, see the [Quickstart](02-quickstart.md). +If you want to quickly try out Serverpod and build something with an AI agent, check out our [Quickstart](02-quickstart.md) guide. ## Next steps -Ready to build something? Follow [Build your first app](../05-build-your-first-app/01-creating-endpoints.md) to create your first endpoint and call it from Flutter. When you are ready to ship, [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) takes your app to production. +Ready to build something for real? Follow [Build your first app](../05-build-your-first-app/01-creating-endpoints.md) to create your first endpoint and call it from Flutter. When you are ready to ship, [Deploy to Serverpod Cloud](../08-deployments/01-deploy-to-serverpod-cloud.md) takes your app to production in just a few minutes.