Project structure

A Boson application is a normal Rust workspace with thin host binaries and product-owned capabilities. The generated layout keeps platform integration explicit without making developers assemble the runtime themselves.

my-app/
├── .boson/
│   ├── project.toml
│   └── config.yaml
├── apps/
│   ├── app/          # shared capability registration
│   ├── migrate/
│   ├── server/
│   └── worker/
├── capabilities/
│   └── items/
│       ├── migrations/
│       └── src/lib.rs
└── Cargo.toml

Host applications

The three binaries are deliberately small. Each creates a boson_runtime::Builder, registers capabilities through the shared apps/app composition crate, and selects one operation:

• run_server() serves public and Admin routes.
• run_worker() processes jobs and event consumers.
• migrate() applies platform and capability migrations.

// apps/server/src/main.rs
boson_runtime::Builder::from_env()
    .register(my_app_app::register_app)
    .run_server()
    .await

Routing every host through the same register_app function guarantees that routes, background work, health checks, scopes, and migrations describe one consistent application.

Capabilities

The starter items capability demonstrates the complete public SDK surface:

• authenticated application routes under /v1/items
• an Admin route under /admin/v1/items
• an items:read Admin scope
• capability-owned SQL migrations
• typed configuration under capabilities.items
• a transactional items.item_created.v1 event
• an event consumer and health check

Add product behavior under capabilities/. Capabilities depend on boson-sdk; they should not import adapters or provider SDKs.

Project manifest

.boson/project.toml tells the CLI which packages to build:

schema_version = 1
name = "my-app"
package_prefix = "my_app"
migrate_package = "my_app_migrate"
server_package = "my_app_server"
worker_package = "my_app_worker"

The CLI discovers the project by walking upward for this file and always loads configuration from .boson/config.yaml. Runtime state and unified logs are written to ignored .boson/run and .boson/logs directories.

Infrastructure definitions are not part of the generated project. Developers connect Boson to infrastructure they own through configuration.