Skip to content

Project structure

As you have seen in the Quickstart tutorial, pavex new is a quick way to scaffold a new project and start working on it. If you execute

pavex new demo

the CLI will create a project with the following structure:

app/
configuration/
server/
server_sdk/
workspace_hack/
Cargo.toml
CONFIGURATION.md
deny.toml
Dockerfile
README.md
rust-toolchain.toml

What is the purpose of all those folders? Why is cargo-px needed to build a Pavex project? Are there any conventions to follow?

This guide will answer all these questions and more.

Summary

If you're in a hurry, here's a quick summary of the most important points.
A Pavex project is a Cargo workspace with at least three crates:

  • An application crate (library), conventionally named app.
    It contains the Blueprint for your API. It's where you'll spend most of your time.
  • A server SDK crate (library), conventionally named server_sdk.
    It's generated by pavex generate, which is invoked under the hood by cargo-px when building or running the project. You should never modify the generated code—your manual changes will be overwritten.
  • A server crate (binary), conventionally named server.
    It is the entrypoint for your application. You'll have to change if you want to tweak the binary entrypoint (e.g. modify the default telemetry setup). Your integration tests live in this crate.

Using the demo project as an example, the relationship between the project crates can be visualised as follows:

graph 
  d[app] -->|contains| bp[Blueprint];
  bp -->|is used to generate| dss[server_sdk];
  dss -->|is used by| ds[server];
  dss -->|is used by| dst[API tests in server];

If you want to know more, read on!