Atomic Microkernel Architecture · Python

One file.
One feature.
Zero wiring.

The Atomic Microkernel Architecture that makes AI-generated code maintainable. Drop a file in, restart — it's live.

Get Started Read the Docs

how it works — live

domains/products/

list_products.py

get_product.py

1 file = schema + route
+ logic + events

No route registration. No main.py edits. No containers.

lines of kernel

pure stdlib

core dependencies

nothing to break

file per feature

schema → logic → events

files of AI context

manifest + plugin

The Bottleneck of Modern Software

Stop mounting V8 Engines on 1920s Chassis

We take frontier LLMs (Claude, GPT, Gemini) — brutal powerhouses — and force them to write code inside legacy human architectures: Clean, Hexagonal, MVC. The physics have changed completely.

V8 Engine in a 1920s Chassis - Architecture Bottleneck

The Shift: High blast radius & fragmented context → Isolated, atomic, single-file locality.

Explore MicroCoreOS ↓

Why it exists

Your AI made a mistake.
How long until you find it?

Layered architecture

~30 min

controllers/user_controller.py

services/user_service.py

dtos/user_request_dto.py

dtos/user_response_dto.py

repositories/user_repository.py

mappers/user_mapper.py

containers.py

routes/__init__.py

One feature scattered across 8 files. The bug hides between the layers.

MicroCoreOS

30 sec

domains/users/plugins/create_user.py

├── Pydantic schema

├── HTTP route

├── business logic

└── event publishing

The whole feature lives in one file. The AI reads 2 files, follows 1 pattern — and so do you.

The Elastic Monolith

Scaling is a tool swap,
not a rewrite.

Try it — swap the infrastructure. Watch how many lines of plugin code change.

create_order_plugin.py plugin code

async def execute(self, data, context=None):

order_id = await self.db.execute(sql, params)

await self.state.set("cart", [])

await self.bus.publish("order.created", ...)

return {"success": True}

The kernel only knows the contract — never the implementation

In-process by default, distributed on demand. Same plugins run unchanged whether the database is SQLite or PostgreSQL — verified by parity test suites, not promises.

Anatomy

A kernel that wires everything by name.

Dependency injection
by parameter name.

def __init__(self,

db, state,

bus, logger):

01 These parameter names are the injected tools.
02 No decorators. No containers. No config files.
03 Testing = pass mocks to the constructor. Done.

Testable by design

Everything is a black box.

Input in, output out — the contract is all that matters. The AI builds each box; the contract keeps it honest.

01 · A plugin is a box

{"name", "price"}

input

create_product

internals: opaque

{"success": true}

output

injected: db = Mock() bus = Mock()

plugin = CreateProductPlugin(http, db, bus, logger)

result = plugin.execute(data)

assert result["success"] is True

No container setup, no network, no database process. Pass mocks to the constructor and assert the contract — in milliseconds.

02 · A flow is a bigger box

flow: order → fulfilment · closed system

create_order

reserve_stock

send_email

boxes inside boxes — each one under contract

out

The AI builds one box at a time against its contract. Chain them and the flow becomes a closed system with its own input and output — tested exactly the same way: what goes in, what comes out. Causal traces verify the path in between.

Happy-path and sad-path trace tests are enforced by linters before code reaches staging. Internals can change freely; contracts cannot break silently.

Zero-config observability

See why it happened,
not just that it did.

Causal event tracing

Every event carries a parent_id. One endpoint rebuilds the full chain.

Tool metrics, auto-timed

Every tool call is measured by ToolProxy. Zero instrumentation code.

OpenTelemetry, one flag

OTEL_ENABLED=true → spans in Jaeger, Tempo or Datadog. Plugins untouched.

GET /system/traces/tree SSE live

trace_id: a3f9…c21

Reconstructed from parent_id — built into the bus

Built for agentic AI

Clear rules. Deterministic architecture.

Rules should guide your methodology — not patch complex, fragmented architectures. MicroCoreOS gives LLMs a clear, single-file boundary where every feature belongs.

auto-generated

AI_CONTEXT.md regenerates on boot

Scans tools, plugins, events and models to write a manifest with exact signatures. Your AI is never out of date.

less context, better code

The AI reads 2 files, not 20

The manifest plus the plugin it is working on. One pattern to follow. Clean, isolated output — instead of context windows full of rules.

10x cheaper api

Prompt Caching & Parallel Agents

Standardized base context means N parallel agents reuse the same token cache. Run 10 tasks in parallel with up to 10x cheaper API costs.

logic-free core

Honest Kernel, no magic

The kernel never retries silently. Resilience lives where the knowledge is — in tools and plugins, explicitly. Your data stays predictable.

Development Lifecycle

ROADMAP

Where MicroCoreOS is heading — from local development to production telemetry.

Phase 01 Completed

Local Foundations

Core DI registry reflection, auto-discovering domain plugins, and self-regenerating AI_CONTEXT.md manifests.

Phase 02 Completed

Database Swaps & Parity

Abstracted DB persistence contract allowing SQLite and PostgreSQL swaps validated by identical unit parity tests.

Phase 03 Completed

Durable Transport & SSE

SQLite durable event queue and in-memory broker with Server-Sent Events tracking correlation/causal trace IDs.

Phase 04 Completed

Tracer Tools & Observability API

Built-in trace records, causal execution trees, ToolProxy auto-instrumentation, and SSE real-time streams under /system/*.

Phase 05 Completed

Distributed Fleet (Redis / Kafka / RabbitMQ)

Zero-code transport swaps (Redis Streams, Kafka, RabbitMQ, SQLite) with native delay capability negotiation and parity test suites.

Phase 06 Completed

Mechanical Plan Validation & Linters

Automated AST Architecture Linters, 15-rule mechanical Plan Validator, devtools isolation domain, and ChaosControl fault injection.

Phase 07 In Progress

Transactional Outbox & Benchmarks

Plugin-layer transactional outbox pattern and MicroCoreBench automated resilience load-testing suite.

Ship features, not wiring.

Join the early-access list for the v0.1.0 release, architecture deep-dives and AI-native design patterns.

No spam. Just pure system engineering.

One file. One feature. Zero wiring.