# Your Serverpod project

https://docs.serverpod.dev/next/concepts/server-fundamentals/your-serverpod-project

A Serverpod project is one workspace holding three Dart packages: your server, a generated client, and your Flutter app. You write data models and endpoints on the server; Serverpod generates everything between them, so your app calls the server through typed Dart methods instead of hand-written networking code. Knowing what lives where makes every other page in this section easier to follow.

Running `serverpod create myproject` generates one workspace with three packages:

```text
myproject/
├── myproject_server/    # Your server: endpoints, models, config, migrations
├── myproject_client/    # Generated client: how your app calls the server
└── myproject_flutter/   # Your Flutter app
```

That is the whole mental model: you work in the server and the app, and Serverpod maintains the client between them. Everything else in the workspace supports those three, and the sections below introduce each piece as you need it.

Expand the full workspace tree.

```text
myproject/
├── pubspec.yaml                  # Workspace root: one `dart pub get` resolves all packages
├── AGENTS.md                     # Instructions for AI agents working in the project
├── .github/                      # CI workflows: analyze, format, and test
├── .vscode/                      # Attach-to-server debug configs and a serverpod start task
├── .agents/                      # Agent skills, plus MCP configs for the editors you picked
├── myproject_server/             # Your server
│   ├── bin/main.dart             # Entry point, calls run() in lib/server.dart
│   ├── lib/server.dart           # The run() function: creates and starts the server
│   ├── lib/src/greetings/        # Example feature: a model file and an endpoint
│   ├── lib/src/auth/             # Endpoints for the scaffolded email sign-in
│   ├── lib/src/web/              # Routes and widgets for the web server
│   ├── lib/src/generated/        # Generated server code (do not edit)
│   ├── config/                   # Run-mode configs, passwords, generator.yaml
│   ├── migrations/               # Database migrations
│   ├── web/                      # Static files and pages the web server serves
│   ├── test/integration/         # Endpoint tests and generated test tools
│   └── docker-compose.yaml       # Container alternative for the database, plus the test database
├── myproject_client/             # Generated client package
│   └── lib/src/protocol/         # Generated calls and models (do not edit)
└── myproject_flutter/            # Your Flutter app
    ├── lib/main.dart             # App code: creates the global Client
    ├── lib/screens/              # Scaffolded sign-in and greetings screens
    ├── lib/driver.dart           # Entry point serverpod start uses to launch the app
    └── assets/config.json        # The server URL the app reads at startup
```

The exact set depends on your create-time choices: the auth endpoints and sign-in screen come with authentication, the web pieces with the web server option, and the agent and MCP files with the editors you picked.

## How the packages relate

The Flutter app depends on the client package, and the client is how the app reaches the server: it holds a typed method for every endpoint you write. Neither the server nor the client depends on the other; instead, the server's `config/generator.yaml` points at the client package (`client_package_path`), and code generation writes the client's contents directly.

The workspace is a Dart pub workspace: each package declares `resolution: workspace`, and a single `dart pub get` at the project root resolves all three.

## Where your code lives, and what is generated

You write two kinds of source files on the server, and both can live anywhere under the server's `lib/`:

- **Model files** (`.spy.yaml`) define your serializable classes and database tables. The template keeps them next to the code that uses them, such as `lib/src/greetings/greeting.spy.yaml`. See [Working with models](https://docs.serverpod.dev/next/concepts/data-and-the-database/models.md).
- **Endpoints** are Dart classes extending `Endpoint`, such as `lib/src/greetings/greeting_endpoint.dart`. Each public method becomes a callable client method: `GreetingEndpoint.hello` is called as `client.greeting.hello(...)`. See [Working with endpoints](https://docs.serverpod.dev/next/concepts/endpoints-and-apis.md).

The scaffolded project follows the same pattern beyond the greeting example: `lib/src/auth/` holds the endpoints behind the default email sign-in, and `lib/src/web/` holds the routes the web server serves.

From those, `serverpod generate` produces the bridge between server and app:

- On the server, `lib/src/generated/` gets the endpoint dispatch code, the protocol description, the pre-configured `Serverpod` class the server starts from, and a Dart class per model.
- In the client package, `lib/src/protocol/` gets the `Client` class with its typed endpoint methods, plus the same model classes for the app's side.
- In `test/integration/test_tools/`, the generated [test tools](https://docs.serverpod.dev/next/concepts/testing/get-started.md).

Generated code is overwritten on every run, so never edit it; the scaffolded analyzer config excludes it for that reason. While [`serverpod start`](https://docs.serverpod.dev/next/concepts/server-fundamentals/running-your-server.md) runs, generation happens automatically when you save; outside a session, run `serverpod generate` yourself.

## The server entry point

The server starts in `bin/main.dart`, which only calls the `run` function in `lib/server.dart`. That function creates the server from the generated `Serverpod` class, registers everything that is not an endpoint, and starts it:

```dart
void run(List<String> args) async {
  // The generated Serverpod class.
  final pod = Serverpod(args);

  // Registrations go here: authentication services and web routes
  // in the scaffolded project, and anything else you add.

  // Start the server.
  await pod.start();
}
```

Endpoints need no registration: the generated `Serverpod` class already carries them all. Web routes, by contrast, are registered imperatively on `pod.webServer`, which is why the scaffolded `run()` contains route setup. When `pod.start()` runs, the server connects to the database, applies pending migrations when started with `--apply-migrations`, connects to Redis if enabled, brings up its servers, and starts background work such as [future calls](https://docs.serverpod.dev/next/concepts/scheduling/overview.md) and [health checks](https://docs.serverpod.dev/next/concepts/operations/health-checks.md).

## The three servers

One Serverpod instance runs up to three servers, each on its own port in development:

- **The API server (8080)** handles incoming endpoint calls from your app. This is the server your generated client talks to.
- **The Insights server (8081)** is a separate, secret-protected server used by Serverpod's tooling. See [Insights](https://docs.serverpod.dev/next/tools/insights.md).
- **The web server (8082)** serves web content: HTML routes, static files, and your built Flutter web app. See [Web server](https://docs.serverpod.dev/next/concepts/web-server/overview.md).

The scaffolded development config also reserves port 8090 for the database and 8091 for Redis.

## The config and migrations directories

The server's `config/` directory holds one YAML file per [run mode](https://docs.serverpod.dev/next/concepts/server-fundamentals/configuration.md#run-modes) (`development`, `test`, `staging`, `production`), the `passwords.yaml` secrets file scaffolded with generated per-environment secrets, and `generator.yaml`, which configures code generation. See [Configuration](https://docs.serverpod.dev/next/concepts/server-fundamentals/configuration.md) for all of them.

The `migrations/` directory starts with one migration that creates your initial schema, and grows as your models change. See [Migrations](https://docs.serverpod.dev/next/concepts/data-and-the-database/database/migrations.md).

After the first server start, a gitignored `.serverpod/` directory also appears in the server package: it holds the [embedded database's](https://docs.serverpod.dev/next/concepts/server-fundamentals/configuration.md#database-backends) data files, one subdirectory per run mode, created by the server on demand.

## Editor and agent files

The workspace ships ready for IDE debugging and AI agents: `.vscode/` contains attach configurations that connect the debugger to a running `serverpod start` session, `AGENTS.md` instructs AI agents on how to work in the project, and, depending on the editors you picked at create time, agent skills are installed under `.agents/` and MCP configuration files register Serverpod's [MCP server](https://docs.serverpod.dev/next/concepts/cli/commands/mcp-server.md) with your editor. The agent configuration files are excluded from version control by the workspace `.gitignore`.

## Related

- [How it works](https://docs.serverpod.dev/next/how-it-works.md): the guided tour of building with Serverpod.
- [Running your server](https://docs.serverpod.dev/next/concepts/server-fundamentals/running-your-server.md): the development loop around this project.
- [Configuration](https://docs.serverpod.dev/next/concepts/server-fundamentals/configuration.md): every file in `config/` in depth.
- [Working with endpoints](https://docs.serverpod.dev/next/concepts/endpoints-and-apis.md): writing the API the client calls.
- [Working with models](https://docs.serverpod.dev/next/concepts/data-and-the-database/models.md): defining your data.