docs: Added page "How it works" by Swiftaxe · Pull Request #496 · serverpod/serverpod_docs

Swiftaxe · 2026-05-13T09:22:24Z

Summary

The documentation currently lacks a dedicated page explaining Serverpod's architecture. This makes it harder for new users to understand how the different parts of the framework fit together.

This PR adds a new "How Serverpod works" page that provides a concise architectural overview, covering:

The project structure
Code generation
Request lifecycle
Full-stack type safety

The focus for this page is on how full-stack type safety is achieved through generating the client project and ORM classes.

Images

Notes for reviewer

As we will move this page into "get started", I assume there is no need for an icon in the sidebar. For now, I kept the icon, previously used for Overview.
The page has a slightly shorter name in the menu, "How it works", while being called "How Serverpod works" on the page. This is intentional. "Serverpod" provides a better context and SEO perspective on the page, but is inferred in the menu.
Verify it covers the essential topics, so that a new user can easily grasp how the core of ServerPod works.
Verify the length is short enough to fit in the get started path.

Test plan

npm run build passes (no broken links).
Render /next locally and confirm the page reads well end-to-end.
Confirm the sidebar lists the new page correctly.

developerjamiu

Document flows well top to bottom. Most of my line-level comments come from the doc templates and Viktor's feedback on the Introduction PR (#495).

developerjamiu · 2026-05-13T10:59:37Z

+title: How Serverpod works
+sidebar_label: How it works
+sidebar_class_name: sidebar-icon-overview
+description: Serverpod's architecture, how project structure, code generation, and request lifecycle provide full-stack type safety


Description should be a complete sentence per the doc templates.

Suggested change

description: Serverpod's architecture, how project structure, code generation, and request lifecycle provide full-stack type safety

description: Understand Serverpod's architecture: the three-package layout, the code generator, and the request lifecycle that gives you full-stack type safety.

developerjamiu · 2026-05-13T11:41:53Z

+
+# How Serverpod works
+
+This page explains Serverpod's architecture: how the project structure, code generation, and request lifecycle work together to provide full-stack type safety.


Most templates says intro should drop the meta-statement like "This page explains"

Suggested change

This page explains Serverpod's architecture: how the project structure, code generation, and request lifecycle work together to provide full-stack type safety.

Serverpod is built around three Dart packages, a code generator, and a typed request lifecycle. Together they give you full-stack type safety from your database to your Flutter app.

developerjamiu · 2026-05-13T12:22:24Z

+
+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, it stays in sync by construction. You do not write serialization code, HTTP calls, or API contracts by hand.


In previous review by Viktor, he suggested to not frame benefit as removing manual code i.e. "write serialization code, HTTP calls, or API contracts by hand" and also keep statements very simple

Suggested change

Because the `_client` package is auto-generated from the `_server` code, it stays in sync by construction. You do not write serialization code, HTTP calls, or API contracts by hand.

Change a model or add an endpoint, and the client follows automatically. The serialization and HTTP code are generated with it.

developerjamiu · 2026-05-13T12:30:10Z

+
+### Session
+
+The `Session` parameter that every endpoint method receives is Serverpod's request context. It gives the method access to the database, cache, authenticated user information, and logging, all of which are scoped to the lifetime of that single request. It is not a singleton; each call gets its own `Session` instance.


Nit: Trying to avoid "singleton" keyword based on the above comment

Suggested change

The `Session` parameter that every endpoint method receives is Serverpod's request context. It gives the method access to the database, cache, authenticated user information, and logging, all of which are scoped to the lifetime of that single request. It is not a singleton; each call gets its own `Session` instance.

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`.

developerjamiu · 2026-05-13T12:40:00Z

+
+## Type safety across the stack
+
+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 for database queries, server-side logic, and the client-side app.


Suggested change

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 for database queries, server-side logic, and the client-side app.

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.

developerjamiu · 2026-05-13T12:44:06Z

+
+## Code generation
+
+The purpose of code generation is to eliminate boilerplate and provide type-safety. Serverpod continuously watches for changes in your `_server` package and the generator automatically creates the necessary code.


Removed the filler words; The purpose and continously

Suggested change

The purpose of code generation is to eliminate boilerplate and provide type-safety. Serverpod continuously watches for changes in your `_server` package and the generator automatically creates the necessary code.

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.

developerjamiu · 2026-05-13T12:47:21Z

+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.
+
+```dart
+var result = await client.greeting.hello('World');


Nit: Dart convention: var should be final for non-reassigned locals.

Suggested change

var result = await client.greeting.hello('World');

final result = await client.greeting.hello('World');

developerjamiu and others added 2 commits May 12, 2026 16:06

docs: Rework Introduction page and remove Overview

ffa4d2e

docs: Added page How it works

33abec1

Swiftaxe requested a review from developerjamiu May 13, 2026 09:22

developerjamiu reviewed May 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Added page "How it works"#496

docs: Added page "How it works"#496
Swiftaxe wants to merge 2 commits into
mainfrom
docs/how-it-works

Swiftaxe commented May 13, 2026 •

edited

Loading

Uh oh!

developerjamiu left a comment

Uh oh!

developerjamiu May 13, 2026

Uh oh!

developerjamiu May 13, 2026

Uh oh!

developerjamiu May 13, 2026

Uh oh!

developerjamiu May 13, 2026

Uh oh!

developerjamiu May 13, 2026

Uh oh!

developerjamiu May 13, 2026

Uh oh!

developerjamiu May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	description: Serverpod's architecture, how project structure, code generation, and request lifecycle provide full-stack type safety
	description: Understand Serverpod's architecture: the three-package layout, the code generator, and the request lifecycle that gives you full-stack type safety.


		# How Serverpod works

		This page explains Serverpod's architecture: how the project structure, code generation, and request lifecycle work together to provide full-stack type safety.

	This page explains Serverpod's architecture: how the project structure, code generation, and request lifecycle work together to provide full-stack type safety.
	Serverpod is built around three Dart packages, a code generator, and a typed request lifecycle. Together they give you full-stack type safety from your database to 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, it stays in sync by construction. You do not write serialization code, HTTP calls, or API contracts by hand.

	Because the `_client` package is auto-generated from the `_server` code, it stays in sync by construction. You do not write serialization code, HTTP calls, or API contracts by hand.
	Change a model or add an endpoint, and the client follows automatically. The serialization and HTTP code are generated with it.


		### Session

		The `Session` parameter that every endpoint method receives is Serverpod's request context. It gives the method access to the database, cache, authenticated user information, and logging, all of which are scoped to the lifetime of that single request. It is not a singleton; each call gets its own `Session` instance.


		## Type safety across the stack

		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 for database queries, server-side logic, and the client-side app.


		## Code generation

		The purpose of code generation is to eliminate boilerplate and provide type-safety. Serverpod continuously watches for changes in your `_server` package and the generator automatically creates the necessary code.

	The purpose of code generation is to eliminate boilerplate and provide type-safety. Serverpod continuously watches for changes in your `_server` package and the generator automatically creates the necessary code.
	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.

	var result = await client.greeting.hello('World');
	final result = await client.greeting.hello('World');

Conversation

Swiftaxe commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Images

Notes for reviewer

Test plan

Uh oh!

developerjamiu left a comment

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

developerjamiu May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Swiftaxe commented May 13, 2026 •

edited

Loading