Kernel & Plugin Architecture
API reference for the central Kernel orchestrator, topological dependency resolver, and Plugin lifecycle protocol.
The Kernel is the central core coordinator for the application lifespan and modular plugins. It assembles registered plugins into a Directed Acyclic Graph (DAG), resolves inter-plugin dependencies topologically, and orchestrates deterministic lifespan transitions.
Class Definition
from zcore import Kernel
# or: from zcore.kernel.engine import Kernel
class Kernel:
def __init__(self) -> None:
...Properties
Prop
Type
Methods
add_plugin
Registers an application plugin instance into the Kernel's local registry.
def add_plugin(self, plugin: Plugin) -> None: ...Prop
Type
setup
Initializes plugin structures and registers core singletons in the IoC container. Sorts dependencies topologically, calls plugin.setup(app) on each plugin, and registers EventDispatcher.
def setup(self, app: FastAPI) -> None: ...Prop
Type
Dependency Resolution (_resolve_dependencies): During setup(), the Kernel builds a dependency graph from declared plugin structures using graphlib.TopologicalSorter. It asserts graph integrity, raising a RuntimeError if a missing dependency is detected or if a cyclic dependency loop exists.
lifespan
Asynchronous context manager governing the active FastAPI application lifespan. Sequentially invokes startup lifecycle phases on sorted plugins and guarantees clean, reversed teardown triggers upon termination, including automatic database and cache connection disposal.
@asynccontextmanager
async def lifespan(self, app: FastAPI) -> AsyncGenerator[None, None]: ...Prop
Type
Lifespan Execution Order:
- Startup (Topological Order):
before_startup$\rightarrow$on_startup$\rightarrow$after_startup. - Shutdown (Reversed Topological Order):
on_shutdownis invoked in strictly reversed dependency order to ensure upstream resources remain available until dependents have closed cleanly. Following plugin shutdowns, automatic teardown of the cache subsystem (close_cache()) and database engine (db_manager.close()) is performed.
The Plugin Protocol
Any domain module intended to plug into the ZCore Kernel must implement the runtime-checkable Plugin protocol:
from typing import Protocol, runtime_checkable
from fastapi import FastAPI
@runtime_checkable
class Plugin(Protocol):
name: str
version: str
dependencies: list[str]
def setup(self, app: FastAPI) -> None: ...
async def before_startup(self) -> None: ...
async def on_startup(self) -> None: ...
async def after_startup(self) -> None: ...
async def on_shutdown(self) -> None: ...Prop
Type