AppManifest — Aquilia Documentation
Comprehensive guide and documentation for AppManifest in the Aquilia framework. View API reference, examples, and implementation patterns.
import from 'lucide-react' AppManifest aquilia.manifest — per-module component registry & request-pipeline declaration Every module in Aquilia has an AppManifest — a dataclass that acts as the definitive component registry for that module. It declares which controllers, services, models, guards, pipes, interceptors, tasks, and middleware the module contributes. The Module in workspace.py is just a name pointer; the manifest.py inside the module directory is the source of truth. No import-time side effects, fully serialisable, inspectable, and fingerprint-stable. workspace.py Workspace("myapp") .module(Module("users")) .module(Module("auth")) .integrate(...) resolves modules/users/manifest.py AppManifest(name="users", ...) , , , , , , , , , ].map(( ) => ( ))} compiled Runtime Subsystems , , , , , , , ].map(( ) => ( ))} exports → imports cross-module DI workspace.py is the orchestrator — manifest.py is the source of truth — the runtime compiles manifests into live subsystems Minimal manifest Create modules/users/manifest.py. Every component is a dot-path string in the form "module.path:ClassName". The : separator is required — __post_init__ validates and raises ManifestInvalidFault if it is missing. Full field reference Field Type Description ))} ComponentRef — typed references with metadata When you need to attach metadata (priority, feature flags, custom config) to a component declaration, use ComponentRef instead of a bare string. The class_path must contain a : separator — ManifestInvalidFault is raised at construction if it does not. ComponentKind — classification enum Used in ComponentRef to classify the component for auto-discovery, filtering, and inspection. All values are lowercase strings. Kind Value Used for ))} ServiceScope — DI lifecycle Scope Lifetime Use for ))} Guards, Pipes, and Interceptors These three types form the v2 request pipeline. They are evaluated before the route handler runs, in order: guards first (gate), then pipes (transform), then interceptors (wrap). All are declared as dot-path strings or ComponentRef. LifecycleConfig — startup and shutdown hooks Hooks are declared as dot-path strings — not callables. This enables lazy loading, manifest serialisation, and fingerprinting without importing the actual function at manifest parse time. The runtime resolves and calls them in topological dependency order. BackgroundTaskConfig — task declarations Declares which @task-decorated functions this module contributes. Tasks listed here are auto-registered with the TaskManager during server startup. The @task decorator provides the runtime metadata (retry policy, queue, timeout); this config gives the manifest layer visibility into what tasks a module owns. Cross-module exports and imports Aquilia's DI system is module-scoped by default — one DI container per module, fully isolated. To share a service across module boundaries, export it from the provider and import the module name in the consumer. The framework resolves all exports into the consumer's DI container automatically at boot. FeatureConfig — conditional activation Feature flags control which services, controllers, middleware, and routes are registered at boot time. Useful for gradual rollouts, A/B testing, or environment-conditional features. auto_discover — convention over configuration When auto_discover=True (the default), Aquilia scans the following subdirectories inside the module package directory and auto-registers anything it finds that matches the expected base classes. Explicit declarations in the manifest take precedence over discovered components. Per-module API versioning Use AppVersioningConfig or the convenience versioning() function to override the workspace-level versioning strategy for a specific module. Fingerprinting — reproducible deploys Every manifest exposes a .fingerprint() method that produces a 16-character SHA-256 hash of the manifest's serialised to_dict() output. This enables reproducible deploy verification — if the fingerprint changes between deploys, you know the component registry changed. Deprecated fields These fields still work at runtime but emit DeprecationWarning via Python's warnings module. Migrate to the current alternatives before the next major release. Deprecated field Replacement What the runtime does ))} Full production manifest ))} )
Go to Homepage