README.md

May 26, 2026 · View on GitHub

Distributed by design. Data-driven by default.

AimDB turns data contracts into the architecture. Define your schemas once and deploy them unchanged across microcontrollers, edge gateways, Kubernetes and the browser, with explicit, typed migrations when the contract evolves.

AimDB is not a storage engine. It's a typed data plane where the Rust type is the wire format.

See it running → Live weather stations streaming typed contracts across MCU, edge and cloud.

Ask your AI about it → Query the live weather mesh in natural language. No install required.

Why AimDB exists

Distributed systems spend most of their complexity budget translating between layers. IDLs, codegen, serialization, schema registries and glue services. AimDB removes that layer by making the Rust type the contract: defined once, compiled unchanged from a no_std microcontroller to the browser.

One type, every tier. The same struct compiles for firmware and cloud. No conversion layer between them.
The buffer defines how data moves. No manual queue wiring, no separate transport config.
No untyped boundaries. Capabilities, like streaming, migration, observability and connectors, are unlocked by traits.

The Next Era of Software Architecture Is Data-First

Quick start

Run it locally in 5 min

cargo new my-aimdb-app && cd my-aimdb-app
cargo add aimdb-core aimdb-tokio-adapter
cargo add tokio --features full

Drop this into src/main.rs:

use aimdb_core::{buffer::BufferCfg, AimDbBuilder};
use aimdb_tokio_adapter::{TokioAdapter, TokioRecordRegistrarExt};
use std::sync::Arc;

#[derive(Clone, Debug)]
pub struct Temperature {
    pub celsius: f32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = Arc::new(TokioAdapter::new()?);
    let mut builder = AimDbBuilder::new().runtime(runtime);

    builder.configure::<Temperature>("temp.indoor", |reg| {
        reg.buffer(BufferCfg::SpmcRing { capacity: 16 })
            .source(|ctx, producer| async move {
                for celsius in [21.0, 22.5, 24.1] {
                    producer.produce(Temperature { celsius }).await.ok();
                    ctx.time().sleep(ctx.time().secs(1)).await;
                }
            })
            .tap(|ctx, consumer| async move {
                let mut reader = consumer.subscribe().unwrap();
                while let Ok(t) = reader.recv().await {
                    ctx.log().info(&format!("temp: {:.1}°C", t.celsius));
                }
            })
            .finish();
    });

    // `.run()` builds the database, collects every producer/consumer/transform
    // future, and drives them all on a single `FuturesUnordered`. It blocks
    // until shutdown. For programmatic access to the `AimDb` handle, call
    // `.build().await?` directly — it returns `(AimDb, AimDbRunner)`.
    builder.run().await?;
    Ok(())
}

cargo run — three temperature readings stream through a typed pipeline. The same code compiles for Embassy on a Cortex-M4 or WASM in the browser by swapping the runtime adapter.

Run a real weather mesh in less than 30 min

A full MCU → edge → cloud mesh: three weather stations, MQTT broker and a central hub.

git clone https://github.com/aimdb-dev/aimdb
cd aimdb/examples/weather-mesh-demo
docker compose up

Walkthrough in the docs

What you get

Three buffer primitives that cover most data-movement patterns:

Buffer	Semantics	Use cases
SPMC Ring	Bounded stream with independent consumers	Sensor telemetry, event logs
SingleLatest	Only the current value matters	Feature flags, config, UI state
Mailbox	Latest instruction wins	Device commands, actuation, RPC

Four capability traits — opt-in, type-checked:

Trait	What it unlocks
`Streamable`	Crossing WASM / WebSocket / CLI boundaries
`Migratable`	Typed schema evolution across deployed fleets
`Observable`	Automatic per-record metrics
`Linkable`	Wire-format connectors

One async API across runtimes. Tokio, Embassy, WASM — swap the runtime adapter, keep the code. → How the runtime abstraction works

Connectors that ship today: MQTT, KNX, WebSocket. Writing your own is one trait impl.

Deep dives: data contracts · source/tap/transform · schema migration · reactive pipelines

How the dataflow fits together

A record is written by a Source, lands in a typed Buffer and fans out to in-process subscribers (Tap) and wire-format bridges (Link → connector):

   Producer                        Consumers
   ────────                        ─────────

                ┌──────────────┐ ───►  Tap   (in-process subscriber)
   Source  ───► │   Buffer     │
   (typed)      │ SPMC / SL /  │ ───►  Tap   (another subscriber)
                │   Mailbox    │
                └──────────────┘ ───►  Link ──► MQTT / KNX / WebSocket

The Rust type system enforces correctness at compile time, buffer semantics enforce flow guarantees at runtime and connectors wire to your infrastructure without an integration layer. The same code compiles for MCU, edge, cloud or browser — see Platform Support below.

Ask your AI about your running system

AimDB ships an MCP server. Point any MCP-compatible client at a running instance and query it in natural language.

Try it against the live demo — no install required. Add this to your workspace:

.vscode/mcp.json:

{
  "servers": {
    "aimdb-weather": {
      "type": "http",
      "url": "http://aimdb.dev/mcp"
    }
  }
}

Then ask: "What's the current temperature in Munich?"

See the MCP server docs for Claude Desktop and other editors or read the deep dive: AI-Assisted System Introspection: AimDB Meets the Model Context Protocol.

Learn more

Quick Start Guide — dependencies, platform setup, your first contract
API reference (docs.rs) — full Rust API
Blog — design notes, deep dives, release write-ups
Live demo — running sensor mesh

Connectors

Protocol	Status	Runtimes
MQTT — `aimdb-mqtt-connector`	✅ Ready	std, no_std
KNX — `aimdb-knx-connector`	✅ Ready	std, no_std
WebSocket — `aimdb-websocket-connector`	✅ Ready	std, wasm
Kafka	📋 Planned	std
Modbus	📋 Planned	std, no_std

Platform Support

Target	Runtime	Adapter	Features	Footprint
ARM Cortex-M (STM32H5, STM32F4)	Embassy	`aimdb-embassy-adapter`	no_std, async	~50KB+
Linux Edge (RPi, gateways)	Tokio	`aimdb-tokio-adapter`	Full std	~10MB+
Containers / K8s	Tokio	`aimdb-tokio-adapter`	Full std	~10MB+
Browser / SPA	WASM	`aimdb-wasm-adapter`	wasm32, single-threaded	~2MB+

Help wanted

We're a small team building something ambitious. The fastest way to help is to take on a scoped piece of it. Each of these is sized for a few hours and includes file pointers, acceptance criteria and a place to ask questions:

#92 — no_std Display for DbError should include numeric fields · 2–3h · core · embedded
#93 — Minimal example: hello-single-latest · 2–3h · docs
#95 — CLI: add aimdb instance ping subcommand · 3–4h · cli
#96 — CI: fail on broken rustdoc links · 1–2h · docs
#97 — Doctests for BufferCfg variants · 2–3h · core · docs
#99 — Async example: hello-mailbox-async · 2–3h · docs
#100 — Async example: hello-single-latest-async · 2–3h · docs
#101 — Async example: hello-spmc-ring-async · 2–3h · docs

See all good first issues →

Comment on an issue if you'd like to take it — we respond within a day. New ideas welcome on Discussions.

Contributing

Found a bug or want a feature? Open a GitHub issue.

Have questions or ideas? Join the discussion on GitHub Discussions.

See the contributing guide for build, test and style requirements.

License

Apache 2.0

Distributed by design. Data-driven by default.

Get started · Live demo · Join the discussion