Architecture — Aquilia Documentation
Comprehensive guide and documentation for Architecture in the Aquilia framework. View API reference, examples, and implementation patterns.
Architecture How Aquilia boots, compiles, and serves requests Overview Aquilia follows a manifest → native runtime architecture. Unlike frameworks that discover components at import time, Aquilia separates declaration from request execution through explicit runtime wiring: Boot Pipeline When you call aq run or instantiate AquiliaServer, the following chain executes: Component Graph The following components are initialized during boot and their relationships: env > .env > config files > defaults) ├── FaultEngine # Typed fault handling with domains and severity ├── Aquilary # Manifest registry │ ├── AquilaryRegistry # Validated app metadata indexed by name │ └── FingerprintGenerator # Content-addressed hashing of artifacts ├── RuntimeRegistry # Compiled runtime state │ ├── DI Containers # One Container per app module (scope: "app") │ │ └── Providers # ClassProvider, FactoryProvider, ValueProvider, … │ ├── Compiled Routes # CompiledController → CompiledRoute[] │ └── Model Schemas # ModelMeta metaclass → table definitions ├── MiddlewareStack # Priority-ordered middleware chain │ ├── ExceptionMiddleware # Global error → Response mapping (priority: 1) │ ├── FaultMiddleware # Fault signal interception (priority: 2) │ ├── ServerRequestScopeMiddleware # Request-scoped child DI container (priority: 5) │ ├── RequestIdMiddleware # Generates X-Request-ID header (priority: 10) │ ├── SessionMiddleware # Session load/save per request (priority: 15) │ ├── AquilAuthMiddleware # Unified auth & identity extraction (priority: 15) │ ├── TemplateMiddleware # Template engine rendering context (priority: 25) │ └── Security & Extensions # ProxyFix (3), HTTPSRedirect (4), Version (5), Static (6), SecurityHeaders (7), HSTS (8), CSP (9), CORS (11), Inspector (11), RateLimit (12), ToolbarInjection (12), CSRF (20), I18n (24), Cache (26) ├── ControllerRouter # URL pattern → CompiledRoute mapping ├── ControllerEngine # Route dispatch + pipeline execution ├── ControllerFactory # Controller instantiation with DI ├── ControllerCompiler # Decorator metadata → CompiledRoute ├── ASGIAdapter # ASGI ↔ Aquilia bridge ├── LifecycleCoordinator # Dependency-ordered startup/shutdown └── AquilaSockets # WebSocket runtime (if enabled)`} language="text" /> Request Lifecycle Every incoming ASGI request flows through this pipeline: Middleware Ordering Middleware is ordered by scope (global ))} DI Container Hierarchy Aquilia creates a hierarchy of DI containers that mirror the scoping model: Configuration Layering Configuration is resolved through a layered merge strategy (higher priority wins): Registry Modes The Aquilary registry operates in one of three modes, affecting validation strictness and debug output: Mode Behavior DEV Relaxed validation, debug error pages, auto-reload, verbose logging, hot-reload support PROD Strict validation, JSON error responses, no debug pages, performance optimizations TEST Relaxed validation, test-specific providers, mock-friendly lifecycle, TransactionTestCase support )
Go to Homepage