Concepts
A mental map of Putnami. No commands, no configuration. Just the territory.
┌──────────────────────────────────────────────────────────┐
│ Platform │
│ (Environments, deploy, scale, observe) │
└──────────────────────────────────────────────────────────┘
▲
│ deploys
│
┌──────────────────────────────────────────────────────────┐
│ Framework │
│ (Web, API, auth, persistence — app patterns) │
└──────────────────────────────────────────────────────────┘
▲
│ uses
│
┌──────────────────────────────────────────────────────────┐
│ Runtime │
│ (Executes application code) │
└──────────────────────────────────────────────────────────┘
▲
│ runs
│
┌──────────────────────────────────────────────────────────┐
│ Workspace │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Project │ │ Project │ │ Project │ │
│ │ (app) │ │ (api) │ │ (library) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Extension │ │ Extension │ ... │
│ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────┘Workspace
The root of everything.
A workspace is a single folder identified by a .putnamirc.json file at the root.
It defines boundaries, shared tooling, and orchestration.
A workspace:
- groups multiple projects
- declares which extensions are active
- is the unit Putnami operates on locally
The workspace does not define how apps are built or where they run.
Project
A distinct piece of your system.
There are two kinds of projects:
- App — Deployable. Has an entry point. Becomes a running process.
- Library — Importable. Shared code used by apps or other libraries.
Projects live inside a workspace and are composed together.
Extension
The extension mechanism of Putnami.
Extensions extend Putnami itself.
They add capabilities such as:
- tooling steps (build, test, lint)
- language support
- frameworks
- platform integrations
Extensions are auto-discovered from workspace dependencies and loaded automatically. They operate at the workspace level.
Extensions do not define application structure directly.
Runtime
The execution environment for application code.
The runtime is managed by Putnami. It is responsible for running apps locally and in production.
Runtime details are intentionally abstracted at this level. Language- and runtime-specific concerns live outside the Concepts layer.
Framework
Reusable patterns for building applications.
Frameworks define how apps are written.
Examples include:
- web rendering
- API routing
- authentication
- persistence
- validation
Frameworks are provided by extensions. You compose only the frameworks your app needs.
Frameworks may have their own internal extension systems. Those are framework concerns, not Putnami concepts.
Environment
An isolated runtime context for an application.
In Putnami, environments are created per branch by default.
A branch maps to an environment.
Typical environments include:
- ephemeral preview environments (one per branch)
- shared staging
- production
Each environment has its own deployment, configuration, and data scope.
Environments are managed by the Platform. You do not manually create or name them.
Platform
The production layer where apps run.
The platform:
- manages environments
- handles deployment and scaling
- provides observability
It connects local development to production execution. You can use Putnami without the Platform, but the Platform unlocks the full workflow.
Summary
- Workspace — organizes things. Learn more
- Project — what you build. Learn more
- Extension — extends Putnami. Learn more
- Framework — structures apps. Learn more
- Runtime — executes code.
- Environment — isolates realities. Learn more
- Platform — runs everything in production. Learn more
Ready to build something?