Architecture

This section explains the framework itself: its core runtime, its contracts and traits, and the dependency rules that keep implementations and adapters replaceable.

The crate catalog is the implementation reference. Each crate page documents the concrete API, modules, and dependencies. This section explains the model those crates implement.

Building an application? Start with the quickstart. This section is the philosophy and core design behind it.

The core in one picture

Every application has the same shape:

client ↔ adapter → trait ← implementation

Clientsbrowser (HTMX)REST consumergRPC clientmessage producer

AdaptersHTML adapterJSON adaptergRPC adapterconsumer adapter

TraitNoteswhat it does — no protocol, no storage

ImplementationsTimescaleDBPostgreSQLremote service callmessage publisherOpenSearch

One concrete adapter per client and one concrete implementation per provider; the composition root selects which. Neither side knows the other — both depend only on the trait.

The framework's core supplies the vocabulary and the lifecycle. It does not choose a database, a transport, or a policy for your application.

Core concern	Defined by	What it decides
Errors, validation, call context, sessions	`iet-core`	The shared types every layer uses
Application lifecycle	`iet-app`	How modules prepare, workers run, and shutdown drains
Runtime execution	`iet-runtime-tokio`	How prepared workers are supervised on Tokio
Configuration	`iet-config`	How typed settings reach composition
Database, cache, auth, authorization, telemetry	Their contract crates	Ports with no concrete transport or storage

What the framework does not do

No runtime service locator and no hidden container.
No reflective module discovery.
No mandatory dynamic dispatch on the core request path.
No implicit database session, transaction, or authentication.

Concrete types are selected once in the composition root. The compiler checks the wiring.

One application · one process

notesprojectstasks

Modules call each other in-process through contracts.

Another application · same module

web APIcommand-line app

notesthe same crate, reused

No copying of the rules — add the crate, compose it.

Read the model

Runtime and lifecycle — how Application, Module, Worker, and Runtime prepare, run, and drain a process.
Contracts and traits — the small set of traits that define composition, calls, persistence, and transport boundaries.
Request lifecycle — how a request becomes a validated operation without coupling the adapter to storage.
How your application is shaped — contract, implementation, adapter, and composition in application code.
Calls and transactions — CallContext, CallScope, and when several statements must share a transaction.
Choosing capabilities — add framework pieces only when a requirement forces them.

Core versus implementation

Question	Read
How does the runtime prepare and drain modules?	Architecture
What traits does a database implementation satisfy?	Architecture, then the crate page
What is the exact public API of `iet-db-timescale`?	Crates
Which crate implements a capability?	Crates
How should I structure my application?	Application model

If a page in the crate catalog explains a framework-wide mechanism rather than a crate's implementation, it belongs here instead.