Glossary¶

Vocabulary shared by the Python and Node.js implementations. When an API name exists in only one runtime, its definition says so explicitly.

A¶

Append-only: A storage model in which the application adds records without modifying or deleting existing ones. It is notably used for immutable audit logs.
Audience-bound (JWT): Describes a JWT whose aud claim limits its use to the intended service. A token issued for service-a must be rejected by service-b.

Controller: The "C" in MIC. A thin layer that orchestrates Model and Interface, such as an HTTP handler or drain worker, without owning domain rules.
Cookiecutter scaffold (Python): The historical Python generator stored in template/. It creates a structured service from a small set of answers. See the Python scaffold.

Dead-letter: The final state of a message that exhausted its attempts. It remains observable and can be handled manually, but is no longer retried automatically.
DomainError: A canonical error that describes a domain violation with a stable code, a message, and optional details. Adapters convert it to a non-transient client response. See domain errors.
Drain: One pass of a worker over a queue or outbox: it claims eligible items, delivers them, then records success, another attempt, or a dead-letter transition.
Dual-key rotation: A deployment window during which the verifier accepts both a current and a previous secret. Issuers migrate to the new key before the old one is removed.

HTTP adapter: A component that translates an HttpRouteSpec to a concrete framework without changing the domain handler. MIC provides FastAPI and Litestar adapters for Python, and Node HTTP, Express, Fastify, Hono, and NestJS adapters for Node.js.
HttpRouteSpec: A framework-neutral HTTP route contract: method, path, handler, name, category, and optional schemas. Adapters in each runtime consume the same concept.
HttpRequestContext: A framework-neutral view of an incoming request: headers, query and path parameters, cookies, and the authenticated principal.
HttpResponseSpec: An explicit handler response made of an HTTP status and a body that the adapter validates and serializes.
HttpSuccessEnvelope: The canonical successful response envelope: {"success": true, "data": <value>, "meta": <object | null>}.

Interface: The "I" in MIC. Everything that connects the domain to external systems: inbound and outbound HTTP, authentication, events, storage, and observability.
Idempotent: Describes an operation that can be repeated without changing its final result. Updating by identifier can be idempotent; appending a new audit event usually is not.

MIC: Model / Interface / Controller. A shared architecture that keeps the domain independent from frameworks and transports. See What is MIC?.
Mirror tests (Python): A convention of the Python implementation: the tests/ tree mirrors the application code and the gate requires 100% line and branch coverage. Node.js has its own native tests, npm archive checks, and published-consumer test; it does not claim this naming convention. See mirror tests.
Model: The "M" in MIC. Everything that describes what the service does: entities, schemas, services, and domain rules, independently from the HTTP framework or persistence mechanism.

Port / Adapter (hexagonal vocabulary): Terms reserved for their established meaning in hexagonal architecture. MIC documentation uses more precise names, such as "HTTP adapter", followed by the relevant framework.
Push vs Pull (service-to-service): Two exchange modes: with push, the producer calls or publishes to the recipient; with pull, the consumer reads available items. MIC favors push for routine delivery and separates historical replay.

Read model: A denormalized projection of information owned elsewhere, optimized for a read use case such as search or listing. It can be rebuilt from its source of truth.

schema.* (Node.js): Executable contract builders from @mic-struct/mic-core. They validate inputs and outputs at runtime while exposing the matching TypeScript types.
ServiceAuthSigner: Signs a service-to-service JWT bound to an explicit audience, lifetime, and set of scopes.
ServiceAuthVerifier: Verifies the signature, expiry, audience, issuer, and scopes of a service-to-service JWT before the handler runs.
Service generator: A tool that produces an editable MIC project with no proprietary format. The Python runtime uses the Cookiecutter template; Node.js provides @mic-struct/create-mic-service. See the Python and Node.js quickstarts.
ServiceHttpClient: An outbound HTTP client that signs service-to-service requests and converts canonical failures to DomainError or TransientError. The Python implementation wraps httpx; the Node.js implementation uses fetch.
StrictSchema (Python): An immutable Pydantic v2 base that rejects unknown fields and revalidates each changed copy. In Node.js, schema.* contracts provide runtime validation without reproducing the Pydantic API.

TransientError: A canonical error that marks a failure likely to succeed after a retry, such as an unavailable database or failing upstream service. Adapters keep it distinct from a permanent DomainError.
Transactional outbox: A pattern in which a service writes domain state and the event to publish in one transaction. A dispatcher later claims and delivers the event under an explicit retry policy.

Worker: A process that handles persisted work, such as a queue or outbox. Its lifecycle, cadence, and hard termination remain controlled by service infrastructure.