🎨 White-Labeling & Branding Roadmap

Owner: Product Engineering Status: Draft Pillar: Configuration & Infrastructure Related: assignments-roadmap.md, architecture

This roadmap defines how Evalium supports Multi-Brand and Agency use cases. Instead of treating branding as a simple "Settings Page" feature, we treat it as a Context Resolution Engine that allows a single Tenant (Training Provider) to present different identities (Coca-Cola, Pepsi) depending on the Assignment or Domain.

---

Phase 1: The Branding Engine (Schema & Resolution)

Goal: Build the backend infrastructure to support sophisticated theming and agency-mode routing immediately, even if the UI is simple.

1.1 Schema: branding_themes

We decouple branding from the Tenant. A tenant can own many themes.

CREATE TABLE branding_themes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,     -- RLS Enforced
    org_unit_id UUID,            -- Optional: Dept-specific default
    
    name TEXT NOT NULL,          -- e.g. "Default", "Client: Pepsi"
    
    -- The Look (JSONB for flexibility without schema churn)
    assets JSONB DEFAULT '{}',
    -- Example: { "logo_url": "...", "favicon_url": "...", "watermark_url": "..." }
    
    colors JSONB DEFAULT '{}',
    -- Example: { "primary": "#0055ff", "secondary": "#eef2ff", "text": "#111827" }
    
    font_config JSONB DEFAULT '{}',
    -- Example: { "family": "Inter", "url": "https://fonts.googleapis.com/..." }
    
    -- The Experience
    email_template_id UUID,      -- Link to specific email layout
    certificate_template_id UUID, -- Link to specific certificate design
    
    is_default BOOLEAN DEFAULT false,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

1.2 Schema: tenant_domains

We prepare the infrastructure for Custom Domains now to avoid hardcoded URL logic later.

CREATE TABLE tenant_domains (
    domain TEXT PRIMARY KEY,     -- e.g. "assessments.acme.com"
    tenant_id UUID NOT NULL,
    branding_theme_id UUID,      -- Optional: Enforce specific theme for this domain
    status TEXT DEFAULT 'pending_dns', -- pending, active, provisioning
    created_at TIMESTAMPTZ DEFAULT NOW()
);

1.3 Logic: The Cascading Resolver

We implement a standardized ResolveTheme(ctx, assignment_id) function used by all delivery handlers (UI, Email, PDF).

Resolution Order:

1. Assignment Override: Does the Assignment explicitly link to a specific branding_theme_id? (Agency Mode). -> Use it.
2. Domain Enforcement: Is the user visiting via assessments.pepsi.com which is linked to a specific theme? -> Use it.
3. Org Unit Default: Does the current Org Unit have a default theme? -> Use it.
4. Tenant Default: Fallback to the Tenant's default theme.
5. System Default: Fallback to Evalium branding.

---

Phase 2: The "Joy" Layer (Smart Assets)

Goal: Make branding effortless for SMBs who are not designers.

2.1 Smart Asset Ingestion

Instead of a dumb file uploader, the backend service:

1. Accepts a Logo upload.
2. Auto-Extracts Colors: Analyses the image to suggest a Primary (Dominant) and Secondary (Accent) hex code.
3. Auto-Generates Favicon: Resizes/crops the logo for browser tabs.
4. Saves these suggestions into the branding_themes row automatically.

2.2 "Agency Mode" Selector

Update the Assignment Creation API (Pillar 3) to accept branding_theme_id.

• Use Case: A Training Company creates an assignment. They select "Theme: Client A".
• Result: The candidate sees Client A's logo, ensuring a seamless brand experience without the Admin needing to log out/in.

---

Phase 3: The Enterprise UI (Self-Service)

Goal: Expose the power of Phase 1 to the end-user via the Admin Panel.

3.1 Advanced Theme Editor

• A UI that writes to the branding_themes JSONB columns.
• Live Preview using the ResolveTheme logic.

3.2 Custom Domain Wizard

• A UI to add rows to tenant_domains.
• Instructions for CNAME setup.
• (Future) Automated SSL provisioning via Let's Encrypt / AWS ACM.

---

Summary of Changes from Original Plan

Feature	Original Plan (Frontend-First)	New Plan (Backend-First)
Theme Storage	Columns on Tenant Table	Dedicated branding_themes Table
Scope	Organization-wide only	Cascading (Assignment > Org > Tenant)
Agency Mode	Not supported until Month 4	Day 1 Support via Assignment Overrides
Custom Domains	Phase 4 (6+ Months)	Infrastructure built in Phase 1
Design Tools	Manual Hex Pickers	Auto-Extraction "Smart Defaults"

This roadmap ensures that Multi-Brand Support is a foundational architectural capability, not a cosmetic layer added later.