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 (SQL database, 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

秉 秉

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.

秉 秉

6.4 DocType Lifecycle Hooks

The runtime execution flow for saving a DocType:

秉 秉

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

6.5 ASGI Middleware Pipeline

Incoming HTTP requests flow through the MiddlewareRegistry in priority order (lower priority runs first / outer layer).

Priority	Middleware	Responsibility
10	RateLimitMiddleware	Drops abuse traffic before request parsing.
15	PayloadDecryptionMiddleware	Decrypts application/jose or application/x-encrypted-json bodies before CSRF, idempotency, auth, and route handlers see the request.
20	CSRFMiddleware	Validates origin and double-submit cookie.
30	IdempotencyMiddleware	Manages duplicate request keys.
50	AuthMiddleware	Runs the AuthChain (Session, Bearer, Header).
55	FederatedRedirectMiddleware	Redirects unauthenticated federated sessions.
60	LocaleResolutionMiddleware	Injects i18n locale context.
200	MetricsMiddleware	Observability and latency tracing.

INCOMING REQUEST
       │
       ▼
┌─────────────────────┐
│ Rate Limit (10)     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Payload Decryption  │  ← application/jose → cleartext JSON
│ (15)                │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ CSRF / Idempotency  │
│ (20 - 30)           │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Auth (50)           │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Route Handler       │
└─────────────────────┘

Placing PayloadDecryptionMiddleware at priority 15 ensures encrypted authentication payloads are decrypted before AuthMiddleware (priority 50) and route DTO validation run, while abusive traffic is still dropped early by rate limiting.

6.6 Zero-Trust Outbox Sealing & Ingress Verification Runtime

For distributed nodes and tamper-proof ledger DocTypes:

EDGE NODE                                           CENTRAL INGRESS CLUSTER
┌──────────────────────────────┐                   ┌───────────────────────────────────┐
│ 1. Controller before_insert  │                   │ IngressVerificationService        │
│    - Compute RFC 8785 hash   │                   │ 1. O(1) Key Active/Revoked Check  │
│    - Dual-sign (WebAuthn     │                   │    (Drops revoked keys instant)   │
│      + Node KeyProvider)     │                   │ 2. Sequence Watermark Pre-check   │
│    - Chained prev_hash       │                   │ 3. Canonical hash verification    │
│ 2. OutboxWorker polls DB     │                   │ 4. Ed25519 & WebAuthn P-256 verify│
│ 3. Dispatches signed envelope│ ──── NATS/HTTP ──>│ 5. Commit to Central Ledger       │
└──────────────────────────────┘                   │    (Or route to _quarantine_dlq)  │
                                                   └───────────────────────────────────┘

1. Edge Sealing: Changes to tamper-proof DocTypes compute a deterministic SHA-256 digest over JCS canonicalized fields, linked to the prev_hash of the sequence stream. If dual_sign = True, the operator's client-side WebAuthn signature is co-signed with the node's KeyProviderProtocol.
2. Central Ingress: Incoming envelopes enter a fast-reject pipeline. Inactive/revoked keys and duplicate sequences are rejected before running asymmetric cryptography, preventing CPU exhaustion.

6.7 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.