Workspace overview

A workspace is the unit of organization in Putnami. It is a single folder identified by a .putnamirc.json file at the root that defines how projects are discovered, how commands run, and how dependencies are resolved across the repo.

Key ideas

• apps/ typically contains deployable applications (convention, not enforced)
• packages/ typically contains shared code (convention, not enforced)
• A .putnamirc.json file at the root identifies the workspace

What a project can be

Putnami treats each project as a distinct unit with its own build/test/deploy jobs. Common shapes include:

• App — a runnable/deployable project (web, API, worker)
• Library — shared code used by other projects
• Runtime — a host for running jobs (e.g., typescript, python, go...)

Typical structure

my-workspace/ apps/ web/ package.json packages/ shared/ package.json .putnamirc.json # workspace configuration package.json # root package.json

Organization patterns (examples)

# flat
<project-a>
<project-b>

# Classic apps + packages
apps/<project>
packages/<project-a>
packages/<project-b>

# Domain-based
domains/<domain>/services/<project>
domains/<domain>/jobs/<project>
domains/<domain>/libs/<project>

Why it matters

• Shared tooling: one lint/test/build workflow
• Shared code: internal libraries are first-class
• Clear boundaries: apps deploy, libraries share

How it works

• Putnami discovers projects from workspace config and package metadata.
• The CLI plans jobs across projects and resolves dependencies automatically.
• Workspace dependency resolution is maintained by Putnami, so jobs run in the right order even when projects depend on each other.

Project discovery (high level)

Putnami discovers projects from your workspace settings (package manager workspaces) and each project's package.json. This means you can organize projects however you like, as long as they are included in workspace discovery.

See also: Concepts

Next steps

• Next: CLI