Configuration Reference

The framework_config.toml file is the central configuration mechanism for Framework M. It defines the structural parameters of the application, installed extensions, and system policies such as logging and compliance.

Schema Overview

By default, Framework M looks for framework_config.toml in the current working directory or its parent directories. The file is parsed and validated against the strongly-typed RootConfig Pydantic model (framework_m_core.config).

[framework]

Core application identity settings.

Key	Type	Default	Description
name	string	"my_app"	The internal identifier of the application.
version	string	"0.1.0"	The current semantic version of the application.

[apps]

Tracks installed module extensions and plugins.

Key	Type	Default	Description
installed	list[string]	[]	A list of installed app identifiers to be loaded during the bootstrap sequence.

[logging]

Configures structured logging and automatic data redaction policies to ensure compliance (e.g., avoiding leaking PII or secrets into log files).

Key	Type	Default	Description
enabled	boolean	true	Whether the structured logging redaction processor is active.
format	string	"json"	Output format. Options: json (ELK/Prod) or console (Pretty/Dev).
redact_keys	list[string]	["password", "token", "authorization"]	Keys to completely replace with ***REDACTED***. Case-insensitive. Note: The default keys are always enforced for security.
mask_keys	list[string]	[]	Keys intended for partial masking (e.g., emails, SSNs). Must not overlap with redact_keys.
mask_char	string	"*"	The character used when masking values.

[!NOTE] For automatic discovery of extensions, CLI plugins, and background jobs, Framework M uses standard Python entry points. See the Framework Entry Points reference for more details.

Example Configuration

[framework]
name = "enterprise_erp"
version = "1.2.0"

[apps]
installed = ["hrms", "payroll"]

[logging]
enabled = true
format = "json"
# These add to the mandatory default secrets
redact_keys = ["api_key", "stripe_secret", "aws_access_key"]
mask_keys = ["email", "phone", "ssn"]
mask_char = "*"

Environment Variable Configuration

In addition to TOML files, Framework M uses environment variables for runtime configuration, particularly in Macroservice and Containerized deployments. These are managed via the WebConfig Pydantic model (framework_m_standard.adapters.web.config).

Prefixing Logic

All framework-specific environment variables must be prefixed with FRAMEWORK_M_ to be correctly loaded into the WebConfig model.

Environment Variable	Type	Default	Description
FRAMEWORK_MODE	string	MONOLITH	Options: MONOLITH or MACROSERVICE. Controls route prefixing and discovery strategy.
FRAMEWORK_M_SERVICE_NAME	string	None	The unique name of the service (e.g., finance). Required in MACROSERVICE mode.
FRAMEWORK_M_API_VERSION	string	v1	The API version to use for namespaced routes.
FRAMEWORK_M_STATIC_BASE_URL	string	""	The base URL for serving static assets (CDNs or Proxies).
FRAMEWORK_M_MFE_PROXY_ENABLED	boolean	false	If true, the backend will proxy unknown MFE assets to remote remotes.
FRAMEWORK_M_DESK_ROUTE_PREFIX	string	"/"	The URL prefix where the Desk UI SPA is mounted. Defaults to root "/" to serve both frontend and backend on the same port.

Mode-Specific Behavior

• MONOLITH: The application serves all local MFEs from its own assets and assumes a flat /api/v1 structure.
• MACROSERVICE: The application automatically prefixes all routes with /api/{service_name}/{version} and uses the JIT Oracle for discovery.

OpenAPI Metadata Customization

Framework M auto-generates the OpenAPI schema (available at /api/schema in Monolith mode, or /schema in Macroservice mode). The title, version, and description metadata are resolved dynamically:

1. Application Title: Resolved from [framework] name in framework_config.toml (which maps to the active Python package name). The framework looks up the package's installation metadata (Name field), converts it to Title Case, and appends " API" (e.g. "Hrms API" or "Enterprise Erp API").
2. Description: Resolved from the package's installation metadata (Summary field). Falls back to a generic description if the package is not installed.
3. Version:
   • In development mode (M_DEV_MODE=true): Resolved from the installed package version.
   • In production mode: Uses the generic api_version configured under [framework] in framework_config.toml (or FRAMEWORK_M_API_VERSION environment variable) to avoid exposing specific package version details for security.

Important

Because WebConfig uses cached singleton loading, standard os.environ patching in unit tests is unreliable. Developers MUST use the monkeypatch fixture (pytest) to override these settings early in the test lifecycle.