Carrier Language

This is a book for enterprise architects who have spent careers watching their best ideas decay in translation.

It is a Tuesday morning at a regional health system. The Chief Medical Officer has just approved a behavioral-health pilot. They need a patient-intake service that captures consent, demographics, and a depression-screeni

Enterprise architecture is often described as the discipline of aligning technology with business strategy. In practice, much of the work is more immediate and more difficult: helping large organizations change without b

Carrier is a language and toolchain for defining enterprise services in a form that is compact, structured, and directly connected to runtime behavior. It gives teams a way to describe the core shape of a service without

Carrier is built around a simple architectural idea: enterprise services should describe their domain shape directly. The important parts of a service should not be buried across framework code, middleware, migration scr

Reading about Carrier is one thing. Building with it is another. This interlude takes thirty minutes from a blank directory to a running service with a generated API contract, schema migrations, and a manifest you can go

A Carrier project is organized around source files, imports, modules, and generated artifacts. The structure is intentionally simple, because enterprise systems become difficult enough without hiding the build graph.

The service declaration is the architectural starting point of a Carrier application. It defines the unit being built and gives the rest of the source a boundary.

Models are where enterprise architecture becomes durable. Routes may change, workflows may be redesigned, and integration patterns may evolve, but data tends to survive. A poorly chosen data model can constrain an organi

Carrier type declarations define structured values used for inputs, outputs, and reusable contract shapes. A model describes persistence. A type describes a contract. They are related — but not the same thing.

Carrier separates pure helper logic, business operations, and transactional boundaries. This separation helps prevent service code from collapsing into route handlers.

Routes are the public edge of a Carrier service. They define how callers interact with business capabilities over HTTP. A route is not just a function with a URL — it is part of the enterprise contract.

Security architecture starts with identity. Before a service can enforce access, it must know who is calling and under what authority. Carrier supports JWT authentication for protected routes.

Authentication answers the question: who is calling? Authorization answers the harder question: what is this caller allowed to do? In enterprise systems, authorization is rarely simple. Access may depend on role, tenant,

APIs are enterprise contracts. Once published, they shape downstream systems, integration timelines, operating models, vendor dependencies, and customer expectations. Carrier's API-first workflow helps because API shape

Enterprise data governance is the discipline of knowing what data exists, who owns it, how it changes, who can access it, and what obligations apply. Carrier helps by making models, policies, routes, and metadata explici

Healthcare systems are unusually demanding. They combine complex workflows, sensitive data, strict privacy obligations, interoperability requirements, clinical safety concerns, and rapidly changing operational needs. Car

A small Carrier service can be understood from a few files. An enterprise Carrier estate may contain many services, domains, modules, policies, integrations, and generated artifacts. At that scale, architecture depends l

Enterprise systems do not only store resources. They run workflows. A claim is submitted, reviewed, denied, corrected, approved, and paid. A patient is referred, scheduled, checked in, assessed, treated, discharged, and

No enterprise service lives alone. Even a well-bounded Carrier service will usually depend on identity systems, data platforms, third-party APIs, legacy applications, messaging infrastructure, reporting systems, and othe

Most production AI systems live in a different world than the one they were prototyped in. The notebook becomes a Flask app, the Flask app becomes a queue worker, the queue worker accumulates a tangle of prompt strings,

Architecture does not stop when code compiles. Enterprise services must build, deploy, run, fail, recover, and provide enough evidence for teams to understand what happened.

Carrier is not only a language for describing services. It is also a delivery workflow. The toolchain helps teams format source, check correctness, build runtime output, generate API descriptions, and produce schema migr

Enterprise delivery is not just a sequence of commands. It is a control system for changing software safely. Carrier fits well into delivery workflows because important service artifacts can be generated and checked from

Architecture Decision Records, or ADRs, are short documents that capture important architectural choices. Carrier makes ADRs more useful because many architectural decisions have direct expression in source and generated

The Carrier manifest is a machine-readable description of the service shape. It is generated under .carrier/manifest.json. For enterprise architects, this file is one of the most important outputs of the Carrier toolchai

Adopting Carrier is not only a language decision. It is an operating-model decision. Carrier changes how services are described, reviewed, built, documented, and governed. The best introduction is not a broad mandate. It

A Carrier reference architecture gives teams a repeatable starting point. It should be opinionated enough to create consistency, but not so rigid that every service is forced into the same shape.

Carrier gives enterprise teams a cleaner way to express service architecture, but it does not prevent poor design by itself. The most common pitfalls come from carrying old habits into a more structured tool.

Enterprise software has spent decades moving between extremes — centralization, decentralization, standardization, autonomy. The hard problem remains the same: how can large organizations change software quickly without

Use the smallest construct that fits the architectural intent. The chart below maps a typical authoring question to the right Carrier construct.

Small services can use a simple layered layout:

Run when API shape matters:

Run when schema shape changes:

healthcare.questionnaire Carrier's healthcare/FHIR-oriented construct for typed questionnaire-style inputs.

This walkthrough stays structural rather than inventing exact Carrier syntax. The goal is to show the shape of building a focused service from scratch.