Alyta uses a base theme + organization-specific overrides system. This gives organizations powerful customization capabilities while keeping a stable, centrally maintained core theme.
Storage & Resolution
Theme files are stored in Azure Blob Storage with two layers:
- Base theme:
themes-v2/{themeId}/theme/{filePath} - Organization overrides:
themes-v2/{themeId}/overrides/{organisationId}/{filePath}
The system resolves files override-first. If a file exists in the organization’s override folder, it is used. Otherwise, it falls back to the base theme. Organizations can also add new files that only exist in their overrides.
Editing & Safety
All edits go through the admin theme editor and are strictly validated on save:
- 512 KB maximum file size
- Extension allowlists per directory (e.g. .fluid for templates, .json for schemas, .css/.js for assets)
- Liquid/Fluid syntax validation
{% schema %}JSON validation
Broken files are rejected before going live. Deleting an override reverts the file to the base version.
Base Theme Seeding & Updates
A startup service automatically syncs the on-disk base theme (wwwroot/themes/origin/) to blob storage using content hashing for efficiency. It also updates the theme version from schema/theme.json.
When a new base version is released:
- Organizations see an “Update available” notice.
- Applying the update creates a snapshot of their current overrides first, then switches to the new base.
Developer Notes
- The seeder currently supports a single base theme (“origin”). Multi-base-theme support would require generalizing the selection and seeding logic.
- Always bump the version number in theme.json when shipping significant changes to the base theme.
