Skip to content

docs: Added page "How it works"#496

Merged
Swiftaxe merged 2 commits into
mainfrom
docs/how-it-works
May 19, 2026
Merged

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

Conversation

@Swiftaxe
Copy link
Copy Markdown
Collaborator

@Swiftaxe Swiftaxe commented May 13, 2026

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

image image

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.

@Swiftaxe Swiftaxe requested a review from developerjamiu May 13, 2026 09:22
Copy link
Copy Markdown
Contributor

@developerjamiu developerjamiu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread docs/03-how-it-works.md Outdated
Comment thread docs/03-how-it-works.md Outdated
Comment thread docs/03-how-it-works.md Outdated
Comment thread docs/03-how-it-works.md Outdated
Comment thread docs/03-how-it-works.md Outdated
Comment thread docs/03-how-it-works.md Outdated
Comment thread docs/03-how-it-works.md Outdated
@Swiftaxe Swiftaxe force-pushed the docs/how-it-works branch from 9088b5e to e47eed1 Compare May 18, 2026 18:34
@Swiftaxe Swiftaxe requested a review from developerjamiu May 18, 2026 18:35
Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com>
@Swiftaxe Swiftaxe force-pushed the docs/how-it-works branch from e47eed1 to a29442c Compare May 18, 2026 18:52
@developerjamiu developerjamiu self-assigned this May 19, 2026
@developerjamiu developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels May 19, 2026
@Swiftaxe Swiftaxe merged commit f7b56e4 into main May 19, 2026
4 checks passed
@Swiftaxe Swiftaxe deleted the docs/how-it-works branch May 19, 2026 11:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants