Module System

Vorte's architecture is built around a modular plugin system. Every major feature — AI, auth, database, caching, queues — is a module that can be loaded, configured, and replaced independently.

Module Class

All modules inherit from BaseModule and declare metadata through ModuleMeta. The framework uses this metadata to resolve dependencies, determine load order, and report status.

mymodule.py

python

Copied!

1	from vorte.modules import BaseModule, ModuleMeta, ModulePriority
2
3	class MyModule(BaseModule):
4	meta = ModuleMeta(
5	name="my_module",
6	description="A custom module for my application",
7	version="1.0.0",
8	priority=ModulePriority.NORMAL,
9	dependencies=["database", "cache"],
10	)
11
12	async def on_load(self) -> None:
13	self.logger.info("MyModule loaded")
14
15	async def on_start(self) -> None:
16	self.logger.info("MyModule started")
17
18	async def on_stop(self) -> None:
19	self.logger.info("MyModule stopped")

ModuleMeta

ModuleMeta is a Pydantic model that describes a module to the framework. Every field is optional except name.

Field	Type	Required	Description
`name`	`str`	Yes	Unique module identifier used in config and CLI
`description`	`str`	No	Human-readable description
`version`	`str`	No	Semantic version string
`priority`	`ModulePriority`	No	Load order priority, defaults to NORMAL
`dependencies`	`list[str]`	No	Names of modules that must load first
`optional`	`bool`	No	If True, load failure does not crash the app
`tags`	`list[str]`	No	Categorization tags for filtering

ModulePriority

Modules are loaded in priority order. Lower values load first. Core infrastructure modules load before application-level modules.

Priority Level	Value	Typical Modules
`CRITICAL`	10	Config, logging, error handling
`HIGH`	20	Database, cache, serialization
`NORMAL`	30	Auth, routing, DI container
`LOW`	40	AI, agents, queue, storage
`DEFERRED`	50	GraphQL, dashboard, metrics

ModuleState

Each module transitions through a defined state machine during its lifecycle.

State	Description
`UNLOADED`	Module has been discovered but not yet loaded
`LOADING`	Module is currently executing its on_load hook
`LOADED`	Module has finished loading but is not yet active
`STARTING`	Module is executing its on_start hook
`READY`	Module is fully operational and accepting requests
`STOPPING`	Module is gracefully shutting down
`STOPPED`	Module has been stopped and is inactive
`ERROR`	Module encountered an error during any transition

Custom Module Example

Below is a complete example of a custom notification module with configuration, dependency injection, and lifecycle hooks.

notificationconfig.py

python

Copied!

1	from vorte.modules import BaseModule, ModuleMeta, ModulePriority
2	from vorte.di import wire
3
4	class NotificationConfig:
5	def __init__(self, provider: str = "email", batch_size: int = 100):
6	self.provider = provider
7	self.batch_size = batch_size
8
9	class NotificationModule(BaseModule):
10	meta = ModuleMeta(
11	name="notifications",
12	description="Multi-channel notification system",
13	version="1.0.0",
14	priority=ModulePriority.LOW,
15	dependencies=["database", "queue"],
16	tags=["messaging", "notifications"],
17	)
18
19	def __init__(self):
20	super().__init__()
21	self.config: NotificationConfig \| None = None
22	self._client = None
23
24	async def on_load(self) -> None:
25	self.config = self.get_config(NotificationConfig)
26	self.logger.info(
27	f"Notifications loaded: provider={self.config.provider}"
28	)
29
30	async def on_start(self) -> None:
31	self._client = self._create_client(self.config.provider)
32	await self._client.connect()
33	self.logger.info("Notification client connected")
34
35	async def on_stop(self) -> None:
36	if self._client:
37	await self._client.disconnect()
38	self.logger.info("Notification client disconnected")
39
40	def _create_client(self, provider: str):
41	clients = {
42	"email": EmailClient,
43	"sms": SMSClient,
44	"push": PushClient,
45	}
46	return clients.get(provider, EmailClient)()
47
48	async def send(self, recipient: str, message: str) -> dict:
49	return await self._client.send(recipient, message)

Registering a Custom Module

Place your module in the modules/ directory of your project. Auto-discovery scans this directory and registers allBaseModule subclasses.

example.py

python

Copied!

1	my-app/
2	modules/
3	__init__.py
4	notifications.py # NotificationModule
5	analytics.py # AnalyticsModule
6	main.py
7	config.yaml

Alternatively, register a module programmatically when you need fine control over instantiation.

example.py

python

Copied!

1	from vorte import Vorte
2	from my_app.modules.notifications import NotificationModule
3
4	app = Vorte(auto_load=False)
5	app.register(NotificationModule)
6	app.load_all()

Built-in Modules

Vorte ships with 21 production-ready modules:

Module	Priority	Dependencies
`ai`	LOW	cache, serialization
`agents`	LOW	ai, database
`auth`	NORMAL	database, serialization
`cache`	HIGH	serialization
`database`	HIGH	serialization
`graphql`	DEFERRED	routing, database
`queue`	LOW	database, cache
`storage`	LOW	serialization

Module System

Module Class

ModuleMeta

ModulePriority

ModuleState

Custom Module Example

Registering a Custom Module

Built-in Modules

Stay in the loop