Settings — Reference
The Settings surface is the site-configuration plane for SGEN. It owns every site-level value the platform reads at runtime — general identity (name, tagline, default operator), SEO defaults, privacy posture, locale and timezone, domain bindings, retention periods, role definitions, and the per-module override layer that other surfaces reference. Anything that asks "what is this site configured to do?" traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before scripting against it, scoping a configuration change, or extending the supported setting families. Customer-facing setting walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Settings live under the Settings module in SG-Admin. The module renders one primary view — a tabbed configuration form grouped by setting family — and exposes a write surface for per-family persistence, per-setting reset to default, role CRUD, domain binding, and a small set of validation actions (verify a domain, test a default, regenerate a derived value).
The module is the most-referenced surface on the platform. Other modules treat Settings as the authoritative source for defaults — the email-service default sender address comes from Settings, the password complexity rules used by Users come from Settings, the retention period for the Activity Log comes from Settings, the per-source size cap used by Import comes from Settings. Surface references to "configured under Settings" across this developer-doc set all point here.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Settings
- URL prefix:
/sg-admin/settings/ - View templates:
application/views/Admin/Settings/
Setting values fall into three shapes — scalars (a single value: site name string, default locale code), structured records (a JSON blob — the title pattern with its tokens, the cookie-banner posture with its layout fields), and collections (an ordered list — the active-locales list, the alias-domain list, the custom-role list). The form renders all three shapes; the underlying store records each setting with a type field that drives validation.
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Settings │├──────────────────────────────────────────────────────────────────────┤│ [ General ] [ SEO ] [ Privacy ] [ Locale ] [ Domains ] [ Roles ] ││ [ Per-module overrides ] │├──────────────────────────────────────────────────────────────────────┤│ General ││ ────────────────────────────────────────────────────────────────────││ Site name [ SGEN Demo ] ││ Tagline [ The CMS for serious teams ] ││ Default operator Jerome Cruz (jerome@sgen.com) [ ⓘ ] ││ Fallback system account sandbox-system (sandbox@sgen.com) [ ⓘ ] ││ Default language English (en) [ ⓘ ] ││ Timezone Asia / Manila (UTC+08:00) [ ⓘ ] ││ Date format YYYY-MM-DD ││ Time format 24-hour ││ ││ [Reset to defaults] [Cancel] [Save] │└──────────────────────────────────────────────────────────────────────┘Actions
The Settings surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
Load family
Returns the current values for a setting family, plus the field-level schema (each field's type, default, validation rules, and the family the value belongs to). The schema is what the form uses to render — including which fields are scalar, structured, or collection.
Save family
Persists the posted values for a setting family. Validation runs at the family level — a save with one invalid field rejects the whole family submission with a structured per-field error list. Partial saves within a family are not supported; the operator either resolves every error or cancels the family edit.
Reset to default
Reverts a setting (or an entire family) to the platform default. The default is the shipped baseline — for shipped families, the platform carries the default in source; for custom families added by extensions, the extension declares its defaults at install time. The reset action is undoable only by reverting the next save.
Verify domain
For a domain entry in the Domains family, runs the verification check. The check resolves the domain's DNS records, confirms they point at the platform, and marks the domain entry as verified on success. Unverified domains can be entered but cannot receive traffic until verification succeeds.
Test default
For families that drive other modules (Privacy → consent text, SEO → title pattern, Per-module overrides → channel defaults), provides a test path that runs the default through the consuming module's render with a sample input. Useful for confirming a title pattern produces the intended output before saving.
Regenerate derived value
A small number of settings are derived from other settings — the site's canonical URL is derived from the primary domain and the TLS posture; the public sitemap URL is derived from the SEO sitemap policy and the canonical URL. The regenerate action recomputes the derived values without touching the source values.
List roles
Returns the role definitions, with role slug, display name, member count, and capability-override count columns. Includes the built-in roles (Administrator, Editor, Viewer) and any custom roles defined on this site.
Create custom role
Adds a custom role. The form prompts for the slug, display name, and a starting capability set (clone-from-existing or empty). On submit the role is available in the user-edit role picker and in the per-module capability gates.
Edit role capabilities
Opens the capability matrix for a role. The matrix shows every capability the platform exposes (across all modules), with the role's current state per capability (granted, denied, inherited). Submitting a change updates the role's capability overrides; the next request from any operator holding the role uses the new map.
Delete custom role
Removes a custom role. The surface checks for member operators before applying — a role with members cannot be deleted until the members are reassigned. Built-in roles cannot be deleted.
Export configuration
Produces a bundle of the current settings (scalar, structured, and collection values across all families), excluding domain entries (which are site-specific) and credentials (which are encrypted at rest and never bundle). Used for site cloning and disaster recovery.
Import configuration
Loads a configuration bundle. Validates the bundle against the platform's current setting schema (a bundle from an older version may carry retired settings or miss new ones). Reports per-family success and skips, with a per-skip reason.
Data model
A setting record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
family_slug | string | Setting family identifier — general, seo, privacy, etc. |
setting_slug | string | Setting identifier within the family. |
value | JSON | The current value. Shape depends on value_type. |
value_type | enum | scalar, structured, collection. |
default_value | JSON | The platform default, retained alongside the current value for reset. |
last_changed_by | integer | The user who last saved this setting. |
last_changed_at | timestamp | Touched on save. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
slug | string | Role identifier. Stable across edits. |
display_name | string | Display label. |
is_built_in | boolean | True for Administrator, Editor, Viewer. Built-in roles can be edited (capability overrides) but not deleted. |
capability_map | JSON | Map of capability identifier → grant / deny. Capabilities not listed inherit from the role's baseline. |
created_at | timestamp | Set on create, immutable. |
updated_at | timestamp | Touched on save. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
hostname | string | The domain name. |
is_primary | boolean | True for the site's canonical domain. Exactly one entry carries this flag. |
verified_state | enum | pending, verified, failed. |
redirect_policy | enum | none, redirect_to_primary, serve_alias. |
tls_state | enum | pending, active, failed. |
verified_at | timestamp | Set on successful verification. |
Capability inheritance: custom roles can either start from a built-in baseline (clone-from-existing) or start empty. The capability_map records explicit grant or deny per capability. A capability not in the map inherits from the role's baseline. The resolution at runtime is: explicit deny wins; explicit grant overrides baseline; absence inherits baseline.
Domain semantics: the primary domain drives the canonical URL the platform emits in sitemaps, OpenGraph tags, password-reset links, and the rest. Alias domains can serve traffic (matching the site) or redirect to the primary, depending on the per-alias redirect_policy. Verification is required for a domain to serve traffic — an unverified domain accepts the entry but produces no live behavior.
A MODULE READS A SETTING│ example: Notifications module reading│ "email_service.default_sender_address"▼┌───────────────────────────┐│ Look up by family + slug │ family=per_module_overrides│ │ slug=email_service.default_sender└─────────────┬─────────────┘│├──► record exists ──► return current value│└──► no record ──► return platform default(defaults table)The consuming module never special-cases "default-or-current".It calls the setting lookup; the surface handles the fallback.Permissions
Access to the Settings surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Settings surface.
Layer 2 — per-action capability. Within SG-Admin, each Settings action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| Load family (general, SEO, locale, privacy) | ✔ | ✔ | ✔ |
| Load family (roles, domains, per-module overrides) | ✔ | — | — |
| Save family (general, SEO) | ✔ | ✔ | — |
| Save family (privacy, locale) | ✔ | — | — |
| Save family (roles, domains, per-module overrides) | ✔ | — | — |
| Reset to default | ✔ | — | — |
| Verify domain | ✔ | — | — |
| Test default | ✔ | ✔ | — |
| Regenerate derived value | ✔ | — | — |
| Create custom role | ✔ | — | — |
| Edit role capabilities | ✔ | — | — |
| Delete custom role | ✔ | — | — |
| Export configuration | ✔ | — | — |
| Import configuration | ✔ | — | — |
Settings-cascade exposure. Settings is the source for default values referenced across the platform — the password complexity rules used by the Users surface come from Privacy; the per-source size cap used by Import comes from Per-module overrides; the channel-default sender used by Notifications comes from Per-module overrides. A change to a setting takes effect on the next read by the consuming module — there is no propagation step. The consuming modules treat the lookup as live.
Last-administrator protection. The platform enforces a hard invariant — at least one operator on the site must hold a role with the manage_settings capability. A capability edit that would remove the last operator's settings authority is rejected with a structured rejection. The protection prevents the site from being locked out of its own configuration.
Domain change side effects. Changing the primary domain triggers cascading recomputations across the platform — the canonical URL changes, the sitemap regenerates, OAuth callback URLs registered with integration vendors stop matching (manual reconnect required), email-link tokens issued under the old domain remain valid until expiry. The surface surfaces a warning before applying a primary-domain change and lists the cascading effects.
Audit. Every save, reset, role create, role capability edit, role delete, domain add, domain verify, domain edit, configuration export, and configuration import emits an Activity Log entry. The log records the acting operator, the family and setting affected, and the change shape (field-level diff for structured records). Configuration changes are among the highest-impact actions on a site — the audit posture is the strictest of any module.
ROLE CAPABILITY RESOLUTION│ operator holds role: "Marketing Editor" (custom)│ baseline cloned from: Editor│ capability map overrides:│ edit_seo_defaults = grant│ delete_post = deny│ request: edit a setting in the SEO family▼┌───────────────────────────┐│ Lookup explicit map │└─────────────┬─────────────┘│├──► capability listed grant ──► allow├──► capability listed deny ──► reject (deny wins)└──► capability not listed ──► fall through to baseline▼ fall through┌───────────────────────────┐│ Lookup baseline (Editor) │└─────────────┬─────────────┘│├──► baseline grants ──► allow└──► baseline denies ──► rejectRelated references
- Users — Reference. Role definitions, the fallback system account, password complexity rules, and the Activity Log retention all live here and feed the Users surface.
- Integrations — Reference. Channel defaults, per-connector-family capability overrides, and the encrypted-credential storage configuration live in the Per-module overrides family.
- Notifications — Reference. Channel defaults (default sender address, default SMS gateway) and delivery-log retention come from Settings.
- Forms — Reference. Default consent text, captcha credentials, and the submissions retention cap come from Settings.
- Import — Reference. Per-source size cap, batch retention period, and default duplicate-handling option come from Settings.
- Pages — Reference. SEO title pattern, description pattern, and default OpenGraph image come from Settings.
- Posts — Reference. Same — the post-listing SEO defaults route through the SEO family.
- Media — Reference. Default media-upload optimization (format, compression) come from Settings.
- Tools — Reference. Activity Log retention, export/import configuration bundle, and the database utility defaults route through Settings.
- SEO — Reference. The SEO family in Settings is the same surface as the dedicated SEO module configuration view — two entry points, one underlying record set.
/docs/settings.