Philosophy & Principles

MicroCoreOS is not just another framework; it's a paradigm shift in how we build applications in the age of AI.

The Problems We're Solving

Every software architecture requires discipline. However, in traditional layered systems (Controller → Service → Repository → DTO), that discipline is spread thin across multiple directories, shared files, and unwritten conventions. When delivery pressure mounts or AI-generated code is introduced, keeping those boundaries intact demands constant cognitive effort.

MicroCoreOS doesn't eliminate the need for discipline; it dramatically reduces the cognitive load of maintaining it by making features strictly self-contained:

• Contained code degradation — if a feature is rushed or imperfect, its technical debt is strictly localized to that single plugin file. It cannot silently pollute a shared 3,000-line service class that 20 other endpoints depend on.
• Effortless code reviews — reviewing a pull request means reading one cohesive file (request schema, route registration, persistence, and execution logic together), rather than tracing diffs across 6 separate layers.
• Lower cognitive load for humans & AI — developers and LLMs focus on one isolated boundary at a time, without needing to maintain the entire repository graph in their working memory.
• Zero cross-domain ripple effects — domain boundaries are strictly decoupled; inter-domain communication happens exclusively through typed events via the event bus.
• Structural conflict prevention — parallel contributors (human or AI agents) build features in dedicated files without colliding on shared central routers, service files, or container configurations.
• Swappable infrastructure — infrastructure logic is isolated in Tools behind strict contracts, so swapping SQLite for PostgreSQL or In-Memory for Redis never touches feature code.

→ See Problems It Solves for a deep dive into each.

The Solution: Atomic Microkernel

MicroCoreOS follows the "1 File = 1 Feature" principle.

🧩 Atomic Plugins

A plugin is a self-contained unit of business logic. It defines its own:

1. Request Schema: Inline Pydantic models.
2. Registration: How it hooks into the system (HTTP, Events).
3. Execution: The actual logic.

By keeping everything in one file, we minimize "Context Saturation". An AI only needs to read the Tool signatures (AI_CONTEXT.md) and the Plugin file to understand or modify a feature.

⚛️ Decoupled Tools

Tools are pure infrastructure. They are:

• Stateless: They provide capabilities (DB, HTTP, Logic) but don't hold domain state.
• Swappable: You can swap compatible infrastructure (like swapping the SQLite db tool for a PostgreSQL one) without changing plugin code.

🤖 AI-Native Design

The system is built to be "read" by AI agents.

• AI_CONTEXT.md: A live manifest generated on boot that tells the AI exactly what tools are available and how to call them.
• Fewer AI errors: By reducing the number of files needed to implement a feature, the surface area for incorrect assumptions shrinks significantly.

Core Tenets

Tenet	Description
Blind Kernel	The kernel orchestrates but knows nothing of business logic.
Tool = Capability	Infrastructure lives in Tools.
Plugin = Logic	Business value lives in Plugins.
Event-Driven	Plugins communicate via events, never direct imports.
Hybrid Async	Seamlessly mix synchronous and asynchronous code.