FlowX

FlowX is a universal application runtime for building AI-native, cloud-native, event-driven, high-performance business applications using compile-time orchestration.

Applications are not collections of services. Applications are networks of business capabilities connected by executable flows.

FlowX turns that sentence into a runtime.

Application  =  Trigger  +  Flow  +  Capability  +  Policy  +  Runtime

There is no Controller, no Mediator, no Handler, no Consumer, no Scheduler. Those are not architectural concepts — they are transport details, and FlowX models all of them as one thing: a Trigger.

// A capability: one unit of business meaning. Transport-agnostic. Testable alone.
[Capability("inventory.reserve", Version = "1.0")]
public sealed class ReserveInventory : ICapability<ReserveRequest, Reservation>
{
    private readonly IInventoryStore _store;
    public ReserveInventory(IInventoryStore store) => _store = store;

    public async ValueTask<Result<Reservation>> ExecuteAsync(
        ReserveRequest input, CapabilityContext ctx, CancellationToken ct)
    {
        var ok = await _store.TryReserveAsync(input.Sku, input.Quantity, ct);
        return ok
            ? Result.Ok(new Reservation(input.Sku, input.Quantity))
            : Result.Fail<Reservation>(InventoryErrors.OutOfStock(input.Sku));
    }
}

// A flow: business intent, composed at compile time. Knows nothing about HTTP or Kafka.
[Flow("order.place", Profile = ExecutionProfile.Durable)]
[HttpTrigger("POST", "/api/v1/orders", Idempotent = true)]
[KafkaTrigger("orders.requested", Group = "order-placement")]
public sealed partial class PlaceOrderFlow : Flow<PlaceOrder, OrderPlacedResult>
{
    protected override void Define(IFlowBuilder<PlaceOrder, OrderPlacedResult> flow) => flow
        .Step<ValidateOrder>()
        .Step<ReserveInventory>().CompensateWith<ReleaseInventory>()
        .Step<CapturePayment>().WithPolicy(Policies.PaymentGateway)
        .Emit<OrderPlaced>()
        .Return(ctx => new OrderPlacedResult(ctx.Get<OrderId>()));
}

That is the whole application. The HTTP endpoint, the Kafka consumer, the retry policy, the saga compensation, the OpenTelemetry spans, the OpenAPI document, the architecture diagram and the machine-readable manifest are generated at compile time from those two files.

The load-bearing idea is layer 3. Everything above it is an adapter and everything below it is a detail — which is why the same flow runs behind HTTP, Kafka or a cron schedule with no change to its body, and why the whole graph can be emitted as a machine-readable manifest at build time.

The specification behind this picture, in diffable Mermaid, is 05-Architecture. Where the two disagree, the specification wins.

FlowX does not sit where MediatR sits. It sits one layer above.

ASP.NET Core / Kafka / gRPC / Cron        ← transport
            ▼
          FlowX                            ← programming model + runtime
            ▼
   Business Capabilities                   ← your code
            ▼
       Infrastructure                      ← databases, brokers, clouds

The differentiator is not "faster mediator". It is: one programming model whose architecture is a compiled, queryable artifact — see 13-AI-Native.

Start here, in order:

Working documents — these change as the build progresses:

src/
├── FlowX.Abstractions/        # contracts only — zero dependencies
├── FlowX.Core/                # flow graph, context, result, policy model
├── FlowX.Compiler/            # Roslyn source generators + analyzers
├── FlowX.Runtime/             # engines: flow, capability, policy, event
├── FlowX.Runtime.Durable/     # journal, replay, leases
├── FlowX.Hosting/             # composition root, options, health
├── FlowX.Cli/                 # flowx new | graph | diff | replay | verify
└── plugins/
    ├── FlowX.Http/  FlowX.Kafka/  FlowX.Cron/  FlowX.Stream/  FlowX.Ai/  ...
tests/
├── FlowX.Architecture.Tests/  # fitness functions — written first
├── FlowX.Compiler.Tests/      # generator snapshot tests
├── FlowX.Runtime.Tests/
└── FlowX.Benchmarks/          # budgets from docs/14-Performance.md, gated in CI
docs/                          # this documentation set
samples/                       # nine reference applications

FlowX is at the start of P0 — the walking skeleton. The specification is complete; the contract surface (FlowX.Abstractions) is written but has not yet been compiled, and no runtime exists.

The specification is the contract: code that contradicts it is a bug in the code, or an ADR that has not been written yet.

CHECKLIST.md carries the honest current state, including what is blocked and why. PLAN.md is what to build next, and 20-Roadmap is the phase plan it sits inside.

P0 exists to attempt to falsify the platform's central bet: that a source generator can emit an execution plan reaching ≤ 5 µs p99 with zero allocations. If it cannot, ADR-0002 is wrong and the thesis is revisited before anything else is built. That is the point of doing it first.

Apache License 2.0 — see LICENSE. Rationale in ADR-0012.