Instance Configuration

Instance configuration fields are the platform-wide settings unique to a particular deployment — things like the support email address, the company VAT number, default currency, or which experimental features are enabled. They differ from Site Settings in that you define the fields yourself rather than working from a fixed list.

When to Use Instance Configuration

• Values that change rarely but need to be reachable from many parts of the platform.
• Values administrators (not developers) should manage.
• Values that differ across environments (dev/staging/prod) and tenants.
• Feature flags for gradual rollouts.

Defining a Field

1. Open Architect Panel → Instance Configuration Fields.
2. Click Add Field.
3. Give it a name (used in code: support_email), a label, a type (text, number, boolean, JSON), and a default.
4. Tick whether tenants can override the global value.
5. Save.

Reading Values

From code: $AM->config('support_email'). The lookup automatically returns the tenant override if one exists, falling back to the global default.

Worked Examples

• Multi-region SaaS: A default_currency field defaults to GBP; UK tenant uses GBP, US tenant overrides to USD, EU tenant overrides to EUR.
• Feature flag: enable_new_dashboard defaults false. Toggle true on dev, then for a pilot tenant, then everywhere.
• Third-party keys: stripe_public_key, stripe_secret_key stored as instance configuration so credentials live in the database (encrypted), not in source code.
• White-label branding: brand_name, support_phone — each tenant overrides for their own branded experience.

Note: Secrets (API keys, passwords) should be marked as encrypted-at-rest. The field type encrypted_text handles this automatically — values are encrypted before storage and decrypted on read.

In multi-tenant deployments, each tenant often needs to override a small subset of global configuration — their brand name, their preferred currency, their Stripe key. Per-tenant overrides keep these surgical changes isolated without forking the entire config.

How It Works

The runtime config lookup checks: (1) tenant override, (2) global value, (3) field default. The first non-null value wins. This cascade applies to every instance-configuration field that has “tenants can override” ticked.

Setting an Override

1. Open Architect Panel → Tenants, click the tenant.
2. Go to the Configuration tab. Every overridable field is listed with its current effective value.
3. Click the value to override; the row turns into an editable input.
4. Enter the new value and save. Effective from the next request.

Common Overrides

• Branding: Logo URL, brand name, support email, footer copy.
• Currency / locale: Default currency, decimal separator, date format.
• Integrations: Per-tenant Stripe / SendGrid / Twilio credentials.
• Feature flags: Pilot tenant gets new feature true, others stay false.

Worked Examples

• SaaS pricing: Tenant A on a custom plan has price_per_user overridden to $12; others use the global $15.
• Tenant A pilots new dashboard: Override enable_new_dashboard to true for them. Bug found? Revert by clearing override. Promoted globally? Set the global value.
• Localised SaaS: US tenant overrides date format to MM/DD/YYYY, UK keeps DD/MM/YYYY.
• Per-tenant Stripe accounts: Each customer charges through their own Stripe account; tenant config holds their public + secret keys.

Tip: Build a “configuration audit” page for support to see at a glance what a tenant has overridden vs inherited. Faster than digging through individual rows during a support call.