fabric

Architecture

Microbus solutions can be seen as comprising of 5 layers:

Applications

Microservices in Microbus are not by themselves runnable, rather they are bundled in applications that manage their lifecycle.

Adaptable topology - Applications can contain any number of microservices, making them a flexible vehicle in the construction of the production topology. A small solution might run all its microservices in a single application, while a larger one might split them across multiple applications deployed to different machines or availability zones. The topology can evolve over time without changes to the microservices themselves.

Local development - For local development, all microservices are typically bundled into a single application that runs in the developer’s IDE. This makes it possible to set breakpoints, step through code and inspect state across microservice boundaries, all within a single process.

Integration tests - Similarly, integration tests are executed against an application that contains the microservice under test and its downstream dependencies.

Solution Microservices

These are the microservices that implement the business logic of your solution. They are built by coding agents in the same way as core microservices and benefit from all the same infrastructure. What distinguishes them is that their logic is specific to your domain rather than being general-purpose framework functionality.

Core Microservices

Microbus comes bundled with a few core microservices that implement common functionality required by most if not all Microbus applications.

HTTP ingress - The HTTP ingress proxy bridges the gap between HTTP-based clients and microservices running on Microbus.

HTTP egress - The HTTP egress proxy relays HTTP requests to non-Microbus URLs.

SMTP ingress - The SMTP ingress microservice captures incoming emails and transforms them to actionable events.

Configurator - The configurator is responsible for delivering configuration values to microservices that define configuration properties. It is a must-have in practically all applications.

Metrics - The metrics microservice aggregates metrics from all microservices in response to a request from Prometheus.

OpenAPI portal - The OpenAPI portal microservice renders a catalog of the OpenAPI documents of each and every microservices.

Token issuer - The token issuer microservice issues and validates tokens in the form of JWTs. Tokens enable the authentication of actors and the authorization of their requests based on a set of claims.

Coding Agents

Coding agents are fully empowered in Microbus to produce code rapidly (RAD). Coding agents generate boilerplate code, business logic, tests and documentation.

Agent rules - The rules file .claude/rules/microbus.md teaches the agent the conventions and patterns of the Microbus framework. It covers project structure, naming conventions, error handling, logging, and the idiomatic ways of using the Connector API. This file is updated with each release of Microbus and should not be edited by hand.

Agent skills - The .claude/skills/ directory contains a collection of predefined workflows that guide the agent step by step when adding, removing or modifying features of a microservice. Skills make the agent’s behavior predictable and its output consistent across microservices and developers.

Global and local AGENTS.md - A global AGENTS.md at the project root provides context applicable to the whole project, while a local AGENTS.md in each microservice’s directory captures design choices, tradeoffs, and rationale specific to that microservice. The local file is maintained by the agent as it works, focusing on the why behind decisions so that future agents can safely evolve the code.

Incremental development - Agents build a microservice one feature at a time — an endpoint, a config property, a ticker, a metric. Each prompt results in a focused, incremental change: new code is added without impacting existing code, tests are written or updated, and the manifest is kept in sync. This keeps changes small, reviewable, and easy for the agent to get right.

Client stubs - Client stubs are created for the microservice’s public endpoints. These stubs are used by upstream clients to call the microservice in a type-safe fashion. For functional endpoints (RPCs), the stubs take care of marshaling the request arguments into a JSON payload.

Integration tests implementation - The integration test harness spins up the microservice under test along with the actual downstream microservices it depends on into a single testable application, allowing full-blown integration tests to run inside go test.

OpenAPI - An OpenAPI document is automatically created with descriptors for each of the microservice’s endpoints.

Automatic documentation - As a coding agent works on a microservice, it automatically maintains documentation alongside the code. This includes the manifest.yaml that catalogs the microservice’s features, the PROMPTS.md audit trail, and the AGENTS.md design record. Documentation stays in sync with the implementation because both are produced by the same agent in the same pass.

Uniform code structure - A uniform code structure is a beneficial byproduct of the way coding agents work in Microbus. A familiar code structure helps agents get oriented quickly.

New project bootstrapping - The bootstrapping of new projects is automated.

Connector Construct

The Connector is the base class of all microservices and provides most of their core capabilities.

Transport

Microbus uses a messaging bus for the transport layer of service-to-service communications.

Unicast 1:1 - Unicast request/response is an emulation of the familiar synchronous 1:1 request/response pattern of HTTP over the asynchronous messaging pattern of the underlying transport bus.

Multicast 1:N - Multicast publish/subscribe enhances the publish/subscribe pattern of the bus by introducing a familiar HTTP interface and a bi-directional 1:N request/response pattern.

Multiplexed connections - Microservices are connected to the messaging bus with a persistent multiplexed connection that enables holding multiple concurrent conversations on a single connection. Multiplexing results in lower resource requirements and a simplified network topology that is less prone to error.

Time budget - Time budget is a depleting timeout that is passed downstream along the call stack. It is the proper way to handle client-to-server timeouts.

Ack or fail fast - Ack or fail fast is a pattern by which the server responds with an ack to the client before processing the request. The client knows to wait for the response only if an ack is received, and fail quickly if it’s not.

Dynamic discovery - A microservice transparently makes itself discoverable by subscribing to the messaging bus. Once subscribed to a subject it immediately starts receiving messages from the corresponding queue. An external service discovery system is not required.

Load balancing - Load balancing is handled transparently by the messaging bus. Multiple microservices that subscribe to the same queue are delivered messages randomly. An external load balancer is not required.

Locality-aware routing - With locality-aware routing unicast requests are routed to the replica of the downstream microservice whose locality is nearest to the upstream’s locality.

Connectivity liveness - A microservice is alive when it is connected to the messaging bus and can send and receive messages. The bus validates the connection using regular pings. Explicit liveness checks are unnecessary.

Observability

Logging - Structured logs are emitted in JSON format to stderr, using slog-style key/value attributes for easy parsing and filtering.

Distributed tracing - Distributed tracing enables the visualization of the flow of function calls across microservices and processes. Tracing spans are automatically captured for each endpoint call.

Metrics - Metrics such as latency, duration, byte size and count are collected automatically for all microservice endpoint calls. Custom metrics may be defined by the developer. Metrics are collected and visualized by Grafana.

Error capture - Errors are unavoidable. When they occur, they are captured, augmented with a full stack trace, logged, metered, traced and propagated up the stack to the upstream microservice.

General

Configuration - Configuration properties are common means to initialize and customize microservices without the need for code changes. In Microbus, microservices define their configuration properties but obtain the runtime values of those properties from the configurator.

Authorization - Microservices may stipulate that incoming requests be authenticated and authorized. Requirements are expressed as boolean expressions over the JWT claims of the actor associated with the request. Requests that do not satisfy the authorization requirements are denied.

Tickers - Tickers are jobs that run on a recurring basis, useful for polling external systems, refreshing caches, running cleanup tasks and similar scheduled work.

Embedded resources - Images, scripts, templates and any other static resources are made available to each microservice by association of a file system (FS).

Internationalization - A specially-named resource text.yaml enables internationalization (i18n) of user-facing display strings.

Distributed cache - The distributed cache is an in-memory cache that is shared among the replica peers of a microservice. It is useful for reducing redundant calls to external systems or databases when multiple replicas serve the same data.

Graceful shutdown - Microservices are shutdown gracefully. All pending requests, goroutines and jobs are drained before the microservice quits.

OSS

NATS - NATS sits at the core of Microbus and makes much of its magic possible. NATS is a full-mesh, highly-available, lighting-fast, real-time, at-most-once, messaging bus that supports dynamic subscriptions. It enables request/response, publish/subscribe, load-balancing and dynamic discovery.

OpenTelemetry - OpenTelemetry is a standard for the collection of metrics, distributed tracing and logs.

Grafana - Grafana’s LGTM stack is a bundle of applications (Loki, Grafana, Tempo, Mimir) that collect and visualize OpenTelemetry.

OpenAPI - OpenAPI is a widely used API description standard. The endpoints of all microservices on Microbus are publicly described with OpenAPI.

JWT - JSON web token (JWT) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

This site is open source. Improve this page.