Runtime View

The Runtime View describes the dynamic behavior of the system, illustrating how components interact during execution.

6.1 Litestar (HTTP Server Lifecycle)

Step	Action
Bootstrap	Build the dependency-injector Container with all discovered modules and settings.
Lifespan	Startup: Shared services (PostgreSQL, NATS, Redis) are initialized from the DI container.
Request Flow	Dispatch incoming HTTP request → Service Layer (provided by DI) → Repository → Controller hooks → Response.

6.2 CLI Command Runtime

   CLI Command call (e.g., m migrate)
   │
   ▼
   Bootstrap (Load settings/ID container)
   │
   ▼
   Command Logic (e.g., MigrationService.apply())
   │
   ▼
   Database Adapter (Executing SQL)
   │
   ▼
   Shutdown (Cleanup)

6.3 Background Jobs (Taskiq Flow)

Background jobs use the same DI container mechanism as HTTP and CLI contexts, ensuring consistent logic across all environments.

   NATS JetStream (Message received)
   │
   ▼
   Taskiq Worker (Bootstrap DI container)
   │
   ▼
   Invoke Job Function (DI provides services)
   │
   ▼
   Service Logic (e.g., ProcessOrderService)
   │
   ▼
   Result (Ack / Fail)

6.4 DocType Lifecycle Hooks

The runtime execution flow for saving a DocType:

1. Incoming Request (HTTP or CLI)
2. Controller.validate() (Business rule validation)
3. Controller.before_save() (Pre-persistence processing)
4. Repository.save() (Persistence to Database)
5. Controller.after_save() (Post-persistence side-effects, e.g., Event emission)
6. Response

6.5 Frontend & MFE Lifecycle (The Browser)

The frontend application (The Desk) follows a two-stage composition process to unify the core framework with modular plugins.

Stage 1: Build-Time Composition

1. Vite Scanner: The framework-m-vite-plugin scans the repository for package.json files with the framework-m metadata.
2. Virtual Module Generation: A virtual module (virtual:framework-m-plugins) is generated, containing dynamic imports for the detected plugins.
3. Monolith vs. MFE: Depending on configuration, Vite either optimizes these into a single shared bundle or produces separate JS entry-points for distributed loading.

Stage 2: Runtime Execution (Boot)

Step	Action
Shell Init	The Browser loads the Shell. The PluginSDK initializes the global PluginRegistry.
Plugin Discovery	Registry iterates over the virtual module and registers each plugin.
Composition	Refine.dev resources, Sidebar menus, and React Router paths are merged from all registered plugins.
Authentication	authProvider verifies the backend session/JWT. If valid, the Desk UI is rendered.
Hydration	The UI uses the frameworkMDataProvider to fetch DocType metadata and records from Litestar.
Live Updates	liveProvider opens a WebSocket connection to the backend for real-time JetStream notifications.