application tier

`application-engine`

Forge framework runtime crate: ForgeApp composer, ModuleRouter<S>, migration runner, registry, TOML config. Consumes application-core's contract.

Forge framework runtime crate: ForgeApp composer, ModuleRouter<S>, migration runner, registry, TOML config. Consumes application-core's contract.

Tier	application
Role	unclassified (baselined)
Path	`crates/application/engine`
Edition	2021
Targets	build-script-build, application_engine, migration_versions
Public items	35 across 9 modules
Tests	25

What it is for

application-engine — Forge framework runtime.

Sprint 55 (2026-05-28) extracted this from forge-control per the sprint 54 architectural restructure. Holds the runtime half of the contract/runtime split:

ModuleRouter — generic route-registration extension (kept

here, not in application-core, because per Sprint 55 Round 3 Gemini pattern: object-safe application_core::ModuleIdentity in application-core for Vec<Box<dyn ...>> ingestion, generic ModuleRouter<S> in application-engine called with concrete state during axum compose).

ForgeApp — composer that holds the pool, registered modules,

and orchestrates migration ordering + router merging at boot.

migrate — migration runner using the shared

forge_migration_log ledger.

registry — EngineRegistry (legacy Engine trait) +

ModuleRegistry (new ModuleIdentity trait).

config — forge.toml parser.

Re-exports application-core for consumer convenience: a single use application_engine::* brings in the engine + the contract types it composes.

Capabilities

`crate root`

application-engine — Forge framework runtime.

Item
`async fn run_platform_migrations(pool : & sqlx::PgPool,) -> Result <(), sqlx::migrate::MigrateError>`

`app (other)`

ForgeApp — the composer.

Item
`pub const ADMIN_PREFIX: & str`

`ForgeApp`

ForgeApp — the composer.

Item
`pub struct ForgeApp<S>`

`ForgeApp<S>`

ForgeApp — the composer.

Item
`ForgeApp<S> :: fn new(pool : PgPool, state : S) -> Self`
`ForgeApp<S> :: fn register <M>(mut self, module : M) -> Self where M : ModuleIdentity + ModuleRouter <S> + 'static,`
`ForgeApp<S> :: fn with_admin_layer <F>(mut self, layer : F) -> Self where F : FnOnce(axum::Router <S>) -> axum::Router <S> + 'static,`
`ForgeApp<S> :: fn into_router(self) -> axum::Router`
`ForgeApp<S> :: async fn boot(self) -> Result <axum::Router, MigrationError>`
`ForgeApp<S> :: async fn boot_with <F>(self, transform : F) -> Result <axum::Router, MigrationError> where F : FnOnce(axum::Router) -> axum::Router,`
`ForgeApp<S> :: fn modules(& self) -> & Box <dyn ModuleIdentity>`
`ForgeApp<S> :: fn pool(& self) -> & PgPool`

`ApplicationSection`

application.toml config parser.

Item
`pub struct ApplicationSection`

`Config`

application.toml config parser.

Item
`pub const CONFIG_FILE: & str`
`pub const CONFIG_FILE_SUPERSEDED: & str`
`pub struct Config`
`Config :: fn load(path : & Path) -> Result <Self, ConfigError>`
`Config :: fn discover(dir : & Path) -> Option <std::path::PathBuf>`
`Config :: fn save(& self, path : & Path) -> Result <(), ConfigError>`

`ConfigError`

application.toml config parser.

Item
`pub enum ConfigError`

`I18nSection`

application.toml config parser.

Item
`pub struct I18nSection`

`ThemeSection`

application.toml config parser.

Item
`pub struct ThemeSection`

`middleware::staging (other)`

Sprint 65: extracted from rust-cms-engine.

Item
`async fn staging_layer(mut req : Request <Body>, next : Next) -> Response`

`IsStaging`

Sprint 65: extracted from rust-cms-engine.

Item
`pub struct IsStaging`

`migrate (other)`

Migration orchestration runner.

Item
`async fn ensure_ledger(pool : & PgPool) -> Result <(), MigrationError>`
`async fn migrate(registry : & EngineRegistry, pool : & PgPool) -> Result <u32, MigrationError>`

`preview (other)`

Responsive preview shell — a reusable staff/dev tool for SSR consumers.

Item
`fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static,`

`EngineRegistry`

Registries — collect registered engines/modules.

Item
`pub struct EngineRegistry`
`EngineRegistry :: fn new() -> Self`
`EngineRegistry :: fn register(mut self, engine : Box <dyn Engine>) -> Self`
`EngineRegistry :: fn engines(& self) -> & Box <dyn Engine>`

`ModuleRegistry`

Registries — collect registered engines/modules.

Item
`pub struct ModuleRegistry`
`ModuleRegistry :: fn new() -> Self`
`ModuleRegistry :: fn register(mut self, module : Box <dyn ModuleIdentity>) -> Self`
`ModuleRegistry :: fn modules(& self) -> & Box <dyn ModuleIdentity>`

`staff (other)`

Sprint 65: extracted from rust-cms-engine.

Item
`fn router <S>(dist_dir : impl Into <PathBuf>) -> Router <S> where S : Clone + Send + Sync + 'static,`

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

application_engine

app
config
middleware
middleware::staging
migrate
module_router
preview
registry
staff

flowchart TD
  n_application_engine["application_engine"]
  n_application_engine --> n_app["app"]
  n_application_engine --> n_config["config"]
  n_application_engine --> n_middleware["middleware"]
  n_middleware --> n_middleware__staging["staging"]
  n_application_engine --> n_migrate["migrate"]
  n_application_engine --> n_module_router["module_router"]
  n_application_engine --> n_preview["preview"]
  n_application_engine --> n_registry["registry"]
  n_application_engine --> n_staff["staff"]

Public surface

`crate root`

Item	What it is
`async fn run_platform_migrations(pool : & sqlx::PgPool,) -> Result <(), sqlx::migrate::MigrateError>`	Apply the canonical Forge platform schema migrations

`app`

Item	What it is
`pub const ADMIN_PREFIX: & str`	Prefix under which every module's admin surface is mounted.
`pub struct ForgeApp<S>`	Composer that holds the pool, state, registered modules, and the accumulated public/admin routers
`ForgeApp<S> :: fn new(pool : PgPool, state : S) -> Self`	Create a new empty app with the given pool and state.
`ForgeApp<S> :: fn register <M>(mut self, module : M) -> Self where M : ModuleIdentity + ModuleRouter <S> + 'static,`	Register a module
`ForgeApp<S> :: fn with_admin_layer <F>(mut self, layer : F) -> Self where F : FnOnce(axum::Router <S>) -> axum::Router <S> + 'static,`	Provide the layer that wraps the admin subtree (typically the RBAC stack)
`ForgeApp<S> :: fn into_router(self) -> axum::Router`	Assemble the final router: public surfaces at root, the (optionally layer-wrapped) admin subtree nested under `ADMIN_PREFIX`, state applied once
`ForgeApp<S> :: async fn boot(self) -> Result <axum::Router, MigrationError>`	Run all registered modules' migrations in registration order, then return the assembled router (state applied) ready for `axum::serve`
`ForgeApp<S> :: async fn boot_with <F>(self, transform : F) -> Result <axum::Router, MigrationError> where F : FnOnce(axum::Router) -> axum::Router,`	Boot, then apply a router transform — e.g
`ForgeApp<S> :: fn modules(& self) -> & Box <dyn ModuleIdentity>`	Borrow the registered module list (useful for tests + admin introspection).
`ForgeApp<S> :: fn pool(& self) -> & PgPool`	Borrow the pool — useful when sharing it with non-module workers.

`config`

Item	What it is
`pub enum ConfigError`	Errors raised when reading/parsing/writing the app config.
`pub const CONFIG_FILE: & str`	The config file a consumer app carries, in preference order
`pub const CONFIG_FILE_SUPERSEDED: & str`	—
`pub struct Config`	Top-level config container.
`pub struct ApplicationSection`	`application` section.
`pub struct ThemeSection`	`forge.theme` subsection.
`pub struct I18nSection`	`forge.i18n` subsection.
`Config :: fn load(path : & Path) -> Result <Self, ConfigError>`	—
`Config :: fn discover(dir : & Path) -> Option <std::path::PathBuf>`	The config file in `dir`, preferring the current name over the superseded one
`Config :: fn save(& self, path : & Path) -> Result <(), ConfigError>`	—

`middleware::staging`

Item	What it is
`pub struct IsStaging`	Request extension flag — true when the request arrived on a staging host
`async fn staging_layer(mut req : Request <Body>, next : Next) -> Response`	—

`migrate`

Item	What it is
`async fn ensure_ledger(pool : & PgPool) -> Result <(), MigrationError>`	Bootstrap the `forge_migration_log` ledger table
`async fn migrate(registry : & EngineRegistry, pool : & PgPool) -> Result <u32, MigrationError>`	Run pending migrations across all registered engines in registration order: 1

`preview`

Item	What it is
`fn router <S>() -> Router <S> where S : Clone + Send + Sync + 'static,`	The `/responsive-preview` router

`registry`

Item	What it is
`pub struct EngineRegistry`	Legacy engine registry — `Box<dyn Engine>` collection
`EngineRegistry :: fn new() -> Self`	—
`EngineRegistry :: fn register(mut self, engine : Box <dyn Engine>) -> Self`	—
`EngineRegistry :: fn engines(& self) -> & Box <dyn Engine>`	—
`pub struct ModuleRegistry`	Module registry — `Box<dyn ModuleIdentity>` collection consumed by `crate::ForgeApp`
`ModuleRegistry :: fn new() -> Self`	—
`ModuleRegistry :: fn register(mut self, module : Box <dyn ModuleIdentity>) -> Self`	—
`ModuleRegistry :: fn modules(& self) -> & Box <dyn ModuleIdentity>`	—

`staff`

Item	What it is
`fn router <S>(dist_dir : impl Into <PathBuf>) -> Router <S> where S : Clone + Send + Sync + 'static,`	Returns an axum sub-router that serves a staff-ui SPA bundle out of `dist_dir` with correct caching headers and deep-link fallback

Re-exports. Exported here, defined elsewhere.

Export	Defined in
`ForgeApp`	`app::ForgeApp`
`ModuleRouter`	`application_core::ModuleRouter`
`ModuleRouter`	`module_router::ModuleRouter`
`{ApplicationSection,Config,ConfigError,I18nSection,ThemeSection,CONFIG_FILE,CONFIG_FILE_SUPERSEDED,}`	`config::{ApplicationSection,Config,ConfigError,I18nSection,ThemeSection,CONFIG_FILE,CONFIG_FILE_SUPERSEDED,}`
`{Engine,I18nBundle,MigrationError,MigrationSet,ModuleIdentity,SeedEntity,ThemeBundle,Vertical,VerticalError,}`	`application_core::{Engine,I18nBundle,MigrationError,MigrationSet,ModuleIdentity,SeedEntity,ThemeBundle,Vertical,VerticalError,}`
`{EngineRegistry,ModuleRegistry}`	`registry::{EngineRegistry,ModuleRegistry}`
`{ensure_ledger,migrate}`	`migrate::{ensure_ledger,migrate}`
`{staging_layer,IsStaging}`	`middleware::staging::{staging_layer,IsStaging}`

Boundary

Depends on no other workspace tier.

Shares tier application with 120 other crates: application-agreements, application-ai, application-analytics, application-approvals, application-assessments, application-audit-log, application-auth, application-billing, … (120 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Tier (ontology)	`application`
Architectural role (taxonomy)	`unclassified (baselined)`
Location	`crates/application/engine`
Vocabulary in force (lexicon)	`current`

Dependencies

Runtime, in this workspace.

Crate	Tier	Optional	Only on
`application-core`	application	no	always

Runtime, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`async-trait`	`^0.1`	—	no	always
`axum`	`^0.7`	`multipart`	no	always
`chrono`	`^0.4`	`serde`	no	always
`serde`	`^1`	`derive`	no	always
`serde_json`	`^1`	—	no	always
`sqlx`	`^0.8`	`runtime-tokio`, `postgres`, `chrono`, `uuid`, `json`	no	always
`thiserror`	`^2`	—	no	always
`tokio`	`^1`	`full`	no	always
`toml`	`^0.8`	—	no	always
`tower-http`	`^0.6`	`fs`, `trace`, `cors`, `request-id`	no	always
`tracing`	`^0.1`	—	no	always
`uuid`	`^1`	`v4`, `v7`, `serde`, `js`	no	always

Development, from outside the workspace.

Crate	Requirement	Features	Optional	Only on
`tempfile`	`^3`	—	no	always
`tower`	`^0.5`	`util`	no	always

Build. None.

Depended on by. 14 workspace crates.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  n_application_auth["application-auth"] -->|uses| SELF
  n_application_billing["application-billing"] -->|uses| SELF
  n_application_calendar["application-calendar"] -->|uses| SELF
  n_application_calendar_recurrence["application-calendar-recurrence"] -->|uses| SELF
  n_application_catalog["application-catalog"] -->|uses| SELF
  n_application_cli["application-cli"] -->|uses| SELF
  n_application_cms["application-cms"] -->|uses| SELF
  n_application_encounters["application-encounters"] -->|uses| SELF
  n_application_identifiers["application-identifiers"] -->|uses| SELF
  n_application_messaging["application-messaging"] -->|uses| SELF
  n_application_parties["application-parties"] -->|uses| SELF
  n_application_party_discovery["application-party-discovery"] -->|uses| SELF
  n_application_planning["application-planning"] -->|uses| SELF
  n_application_taxonomy["application-taxonomy"] -->|uses| SELF
  SELF["application-engine"]
  SELF -->|runtime| n_application_core["application-core"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Kind	Name	Source
custom-build	`build-script-build`	`build.rs`
lib	`application_engine`	`src/lib.rs`
test	`migration_versions`	`tests/migration_versions.rs`

Error model

Error type	Named by
`ConfigError`	declared, no public signature returns it

Operational characteristics

Property	Evidence
async public surface	yes
async runtime	yes
database access	yes
network I/O	yes
unsafe code	none detected
environment variables	none detected

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

No environment variable is read with a literal name anywhere in this crate. A variable whose key is computed at run time cannot be listed here, and is not claimed to be absent.

14 workspace crates depend on this one: application-auth, application-billing, application-calendar, application-calendar-recurrence, application-catalog, application-cli, application-cms, application-encounters, application-identifiers, application-messaging, application-parties, application-party-discovery, … (14 total).

Verification

Kind	Count
Unit tests	23
Integration tests	2
Examples	0
Doctests	0

Evidence by module. How often each public module is named by something executable.

Module	Tests	Examples	Consumers
`crate root`	1	0	0
`app`	2	0	1
`config`	7	0	4
`middleware::staging`	2	0	1
`migrate`	2	0	4
`preview`	1	0	7
`registry`	2	0	1
`staff`	1	0	7

What the tests establish, by name:

every_platform_migration_version_is_claimed_by_exactly_one_file — tests/migration_versions.rs
the_ratchet_detects_a_collision — tests/migration_versions.rs
admin_layer_wraps_only_the_admin_subtree — src/app.rs
admin_nested_under_prefix_public_at_root — src/app.rs
a_consumer_app_written_before_the_rename_still_parses — src/config.rs
discovery_falls_back_to_the_superseded_filename — src/config.rs
discovery_finds_nothing_in_an_empty_directory — src/config.rs
discovery_prefers_the_new_filename — src/config.rs
the_new_section_name_parses — src/config.rs
writing_emits_the_new_section_name — src/config.rs
detects_dev_subdomain — src/middleware/staging.rs
rejects_apex_and_local — src/middleware/staging.rs
rejects_substring_matches — src/middleware/staging.rs
ledger_ddl_is_idempotent_shape — src/migrate.rs
ledger_status_values_are_checked — src/migrate.rs
migration_set_is_descriptive — src/migrate.rs
accepts_public_page_paths — src/preview.rs
escape_neutralizes_attribute_breakers — src/preview.rs
rejects_disallowed_charset — src/preview.rs
rejects_external_and_sensitive — src/preview.rs
rendered_html_frames_the_path_three_times — src/preview.rs
rendered_html_is_a_device_switcher — src/preview.rs
hashed_css_is_immutable_but_handwritten_is_not — src/staff.rs
hashed_wasm_and_js_are_immutable — src/staff.rs
html_and_unknown_are_revalidated — src/staff.rs

Documentation coverage

Measure	Documented	Total
Public items with rustdoc	25	35
Public modules with a `//!` block	9	9

pie showData
    title Public items with rustdoc
    "Documented" : 25
    "No rustdoc detected" : 10

Metrics

Metric	Value
Rust source files	10
Source lines	1223
Code lines	770
Public API items	35
Public modules	9
Tests	25
Examples	0
Cargo features	0
Direct runtime dependencies	13
Workspace reverse dependencies	14

pie showData
    title Public API by kind
    "constant" : 3
    "enum" : 1
    "function" : 6
    "method" : 17
    "struct" : 8

pie showData
    title Rust source composition
    "Code" : 770
    "Blank or comment" : 453

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.

All application · Manual