Architecture

Small, separate layers underneath; one coherent experience on top. Dependencies only ever point down, and a layer you do not use is not in your binary.

Layers

Layer	Contains	Today
L3 · Experience	The `rustclamp` facade, and later a CLI, macros, recipes and templates.	Facade works the rest Planned
L2 · Modules	Integrations: HTTP, CLI, worker, databases, messaging.	Planned — only example targets exist
L1 · Coordination	Kernel and Runtime; later configuration, observability, testing.	Kernel Prototype Runtime Planned
L0 · Foundations	Core contracts and small primitives: `Clock`, module and capability identities.	Prototype

Crates

Package	Role	Depends on
`rustclamp`	Facade: `Clamp::run` and the prelude	nothing
`rustclamp-core`	Domain-neutral contracts: modules, capabilities, contributions	nothing
`rustclamp-kernel`	Resolution, cycle detection, projection, freeze	Core
`rustclamp-runtime`	Execution-environment contracts (scaffold)	nothing yet

Four repositories, one package each. A generated local workspace ties them together for development; Git ownership stays separate (ADR 0001). A crate boundary has to earn its existence through dependency isolation, portability or ownership — not aesthetics.

The composition path

Independent Rust components
          │
          ▼
       Modules
          │
          ▼
Capabilities + Contributions
          │
          ▼
  Process projection
          │
          ▼
    Minimal Kernel
          │
          ▼
 Running application

This is the design direction. Projection, resolution and freeze exist as prototypes; a single end-to-end pipeline from blueprint to a running production process does not exist yet.

Non-negotiables

Rule	Why	Enforced
No `unsafe`	The framework should not ask for more trust than Rust itself.	`unsafe_code = "forbid"` in every crate
Documented public API	Contracts are the product; undocumented ones are accidents.	`missing_docs = "deny"`
Zero third-party dependencies	Unused architecture must cost nothing, and your supply chain stays yours.	Boundary tests
No globals, no service locator	Hidden coupling and untyped lookup are what the framework exists to remove.	By construction: no registry, `TypeId` or `Any` map
Ambiguity is an error	“Last registration wins” hides real bugs.	Resolver tests
Immutable after freeze	Runtime behaviour stays predictable and inspectable.	Compile-fail doc test
Measured, not asserted	Cost claims need a control and raw samples.	Evidence with caveats

What Clamp is not

Not a web framework, an async runtime, an ORM, a dependency-injection container, a virtual machine or an AI framework. Not a replacement for Tokio, Axum, SQLx or Serde. Clamp coordinates the libraries that already do those jobs well — integrate before reinventing.