Architecture

This section documents the internal design decisions and guarantees of grelmicro.

• Concurrency runtime: Why grelmicro targets asyncio directly and not Trio or AnyIO.
• Backends and Adapters: How Providers, Components, Backends, and Adapters fit together.
• Configuration: Explicit construction paths, from_config(...), optional env resolution where it fits, and the library-not-app boundary.
• Live reconfiguration: Atomic config swap on a live component, the Reconfigurable mixin, and reader safety.
• Import Strategy: Why backends are imported from submodules, not re-exported.
• Plugins: Entry-point groups that let third-party packages register Providers and Adapters.
• Multiple apps: When two Grelmicro apps can run concurrently, and why Log, Trace, and Metrics are the exception.
• Decorators: Which decorators take the bare @deco form, which require @deco(...), and which wrap sync functions.
• API Conventions: Constructor and factory rules: positional name on patterns, keyword-only name on components, factory classmethods for algorithms.
• Sync from thread: How a synchronous handler calls an async primitive, and why the entry point is explicit.
• Coordination: Worker identity, token generation, lock design, and cleanup strategy.
• Outbox: The dual-write problem, the staging table, and how the relay delivers at least once.
• Graceful shutdown: What happens between SIGTERM and SIGKILL, and how each component drains.
• Kubernetes Backend: Lease resources, optimistic concurrency, and name sanitization.
• SQLite Backend: WAL mode.
• Tracing: Context stack, concurrency safety, and decoupled layering.
• Testing: micro.override(...) block and pytest conftest recipe.