Skip to content

docs: Add project anatomy page and deepen the Server fundamentals section#687

Open
developerjamiu wants to merge 1 commit into
mainfrom
concepts-phase3-section1-server-fundamentals
Open

docs: Add project anatomy page and deepen the Server fundamentals section#687
developerjamiu wants to merge 1 commit into
mainfrom
concepts-phase3-section1-server-fundamentals

Conversation

@developerjamiu

Copy link
Copy Markdown
Contributor

Deep review and rework of the Server fundamentals section, with every technical claim verified against the Serverpod 4.0.0-beta.0 source and a project created with the 4.0.0-beta.0 CLI.

New page

  • Your Serverpod project: the section opener explaining what serverpod create generates. Starts with the three-package mental model and a short tree, with the full annotated workspace tree in a collapsible. Covers package relations (pub workspace, dependency direction), where user code lives vs generated code, the server entry point (bin/main.dart, run(), pod.start()), the three servers and their ports, the config and migrations directories, the .serverpod embedded-database directory, and the editor/agent files.

Reworked pages

  • Running your server: the dev loop now includes the database leg (embedded PostgreSQL). Adds degraded-start recovery, the app launch panel (Ctrl+R), --docker, single-instance behavior, run-mode gating of app launches, and new "Run the server directly" and "Choose a server role" sections (monolith / serverless / maintenance semantics). Documents the key notation precisely: shortcuts are unshifted presses, Shift variants are written out, and Shift+M / Shift+P force a migration even past data-loss warnings. Notes that P is not shown in the bottom bar.
  • Configuration: fixes the source-order contradiction in the overview and the websocketPingInterval example nesting (it is a top-level key; the nested form was silently ignored). Adds a Run modes section, embedded PostgreSQL under Database backends, the SQLite session-log limitation, dedicated secret environment variables with their precedence, and aligns the example with the scaffolded config/development.yaml. Secrets are restructured example-first.
  • Modules: corrects the module reference example (AuthUser lives in serverpod_auth_core; references resolve by effective nickname only, and an override replaces the default), pins beta versions exactly, and rewrites the overview reader-first.

Reference and consistency fixes

  • Configuration reference: corrected consoleEnabled/consoleLogFormat defaults, new Dart-only options (healthCheckInterval, experimentalDiagnosticHandlerTimeout), and password environment variables.
  • Working with endpoints: generation guidance now leads with serverpod start's automatic generation; serverpod generate remains as the no-session path.
  • Logging: corrected the console-logging default and retargeted a stale pointer; same pointer fix in Streaming and Scheduling configuration.
  • How it works: links to the new anatomy page.

@developerjamiu developerjamiu requested a review from Zfinix July 15, 2026 10:23
@developerjamiu developerjamiu self-assigned this Jul 15, 2026
@developerjamiu developerjamiu added documentation Improvements or additions to documentation enhancement New feature or request labels Jul 15, 2026
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.

1 participant