Whitelabel Feasibility Assessment - S5 Slidefactory¶

Date: 2025-11-04 Author: Claude Objective: Assess feasibility of converting S5 Slidefactory to a whitelabel solution with configurable CLIENT_NAME, CLIENT_LOGO, and CLIENT_LOGO_LARGE environment variables.

Executive Summary¶

Feasibility: ✅ HIGH - The whitelabel conversion is highly feasible with LOW-MEDIUM risk.

Estimated Effort: 4-8 hours of focused development work Risk Level: LOW-MEDIUM Recommended Approach: Incremental implementation with environment variable defaults

Current Brand References Analysis¶

1. Sportfive References (7 occurrences)¶

Critical (UI/Frontend) - 4 files¶

Non-Critical (Documentation/Reports) - 2 files¶

2. S5 References (~50+ occurrences)¶

Critical (User-Facing) - 6 files¶

Non-Critical (Infrastructure/Docs) - 40+ files¶

• Git configuration (.git/config)
• REPORTS directory (historical documentation)
• setup.py, alembic/README (dev infrastructure)
• All are LOW impact - mostly internal/historical

3. Logo Files (4 Sportfive-branded images)¶

Critical Assets¶

/static/img/sportfive_logo_red.png      [PRIMARY - Navigation/Chat]
/static/img/bannerlogo.png              [PRIMARY - Login page]
/static/img/sportfive_logo.png          [UNUSED?]
/static/img/sportfive_small.png         [UNUSED?]
/static/img/sportfive_large.png         [UNUSED?]

Generic Assets (Keep as-is)¶

• Favicons (favicon-*.png) - Generic, no branding
• Icons directory - Generic PWA icons
• Other images (gradient.jpg, light.jpg, etc.) - Generic

4. Brand Color (#ee0000 Sportfive Red) - 8 occurrences¶

Proposed Whitelabel Solution¶

Environment Variables¶

# Client Branding
CLIENT_NAME="Slidefactory"                    # Default fallback
CLIENT_LOGO="/static/img/logo.png"            # Small/square logo for nav
CLIENT_LOGO_LARGE="/static/img/logo_large.png" # Banner logo for login
CLIENT_PRIMARY_COLOR="#ee0000"                 # Brand primary color

# Optional additional variables
CLIENT_TITLE="Slidefactory"                    # Browser/API title
CLIENT_DESCRIPTION="AI-driven presentation automation platform"

Implementation Plan¶

Phase 1: Configuration Layer (1-2 hours)¶

File: app/config.py

class Settings(BaseSettings):
    # ... existing settings ...

    # Branding Configuration
    CLIENT_NAME: str = "Slidefactory"
    CLIENT_LOGO: str = "/static/img/logo.png"
    CLIENT_LOGO_LARGE: str = "/static/img/logo_large.png"
    CLIENT_PRIMARY_COLOR: str = "#ee0000"
    CLIENT_TITLE: str | None = None  # Defaults to CLIENT_NAME
    CLIENT_DESCRIPTION: str = "AI-driven presentation automation platform"

    @property
    def client_title(self) -> str:
        return self.CLIENT_TITLE or self.CLIENT_NAME

Phase 2: Template Updates (2-3 hours)¶

1. Base Template (templates/includes/base.html.j2)

{# Before #}
<img class="logo-round" src="/static/img/sportfive_logo_red.png" alt="Logo">

{# After #}
<img class="logo-round" src="{{ settings.CLIENT_LOGO }}" alt="{{ settings.CLIENT_NAME }} Logo">

• Update 2 logo references in base template
• Update meta theme-color to use {{ settings.CLIENT_PRIMARY_COLOR }}
• Ensure settings object is passed in template context

2. Login Page (app/auth/templates/signin.html.j2)

{# Before #}
<img src="/static/img/bannerlogo.png" alt="SportFive Logo">

{# After #}
<img src="{{ settings.CLIENT_LOGO_LARGE }}" alt="{{ settings.CLIENT_NAME }} Logo">

3. Chat Widget (app/chat/templates/n8n_chat_embedded.html.j2)

{# Update logo #}
<img src="{{ settings.CLIENT_LOGO }}" alt="{{ settings.CLIENT_NAME }} Logo" class="logo-round">

{# Update CSS variables #}
<style>
    :root {
        --primary: {{ settings.CLIENT_PRIMARY_COLOR }};
        --chat--color-primary: {{ settings.CLIENT_PRIMARY_COLOR }};
    }
</style>

4. Chat Widget CSS (static/css/chat_widget.css)

/* Update CSS variable to use env or default */
:root {
  --chat--color-primary: var(--brand-primary, #ee0000);
}

Phase 3: Application Title Updates (1 hour)¶

1. FastAPI App (app/main.py)

# Before
app = FastAPI(title="S5-Slidefactory", ...)

# After
app = FastAPI(title=settings.client_title, ...)

2. Account Page (templates/account.html.j2)

{% block title %}{{ settings.CLIENT_NAME }}{% endblock %}

3. CLI (cli/main.py)

# Make CLI references generic or read from config
description=f'{settings.CLIENT_NAME} - Unified CLI for API management'

Phase 4: Asset Management (1-2 hours)¶

Create Generic Logo Structure:

/static/img/
  ├── logo.png              # Default small logo (copy sportfive_logo_red.png)
  ├── logo_large.png        # Default banner logo (copy bannerlogo.png)
  └── branding/             # Original Sportfive assets (archived)
      ├── sportfive_logo_red.png
      ├── sportfive_logo.png
      ├── sportfive_small.png
      ├── sportfive_large.png
      └── bannerlogo.png

Logo Requirements Documentation: - Small logo: Square or circular, 64x64 to 128x128px, transparent background - Large logo: Banner format, max height 80px, transparent background - Supported formats: PNG (preferred), SVG

Phase 5: Documentation Updates (30 minutes)¶

Create: BRANDING.md

# Whitelabel Branding Configuration

## Environment Variables

- CLIENT_NAME: Your company/product name
- CLIENT_LOGO: Path to small logo (navigation/chat)
- CLIENT_LOGO_LARGE: Path to banner logo (login page)
- CLIENT_PRIMARY_COLOR: Hex color code for primary brand color

## Logo Specifications

### Small Logo (CLIENT_LOGO)
- Dimensions: 64x64 to 128x128px
- Format: PNG with transparent background
- Usage: Navigation bar, chat widget, favicon source

### Large Logo (CLIENT_LOGO_LARGE)
- Dimensions: Variable width x 60-80px height
- Format: PNG with transparent background
- Usage: Login page, headers

## Examples

See `examples/branding/` for sample configurations.

Update: README.md - Replace "S5 Slidefactory" with generic "Slidefactory" or use templating

Risk Assessment¶

LOW RISK ✅¶

1. Logo Path Changes
2. Risk: Broken images if paths incorrect
3. Mitigation: Use fallback defaults, add existence checks

4. Impact: Visual only, no functionality loss

5. CSS Variable Updates

6. Risk: Styling issues with invalid color codes
7. Mitigation: Validate hex color format, provide defaults

8. Impact: Cosmetic only

9. Template Context

10. Risk: Settings object not available in all templates
11. Mitigation: Update base template context injection
12. Impact: Easy to test and fix

MEDIUM RISK ⚠️¶

1. PWA Manifest & Meta Tags
2. Risk: Cached manifests may cause issues
3. Mitigation: Update cache-busting, document cache clearing

4. Impact: Users may need to clear browser cache

5. Documentation Consistency

6. Risk: Scattered S5 references in REPORTS/docs
7. Mitigation: Accept as historical, update only critical docs
8. Impact: Confusing for new users, but non-functional

NEGLIGIBLE RISK ✨¶

1. Git Configuration
2. .git/config references are internal only

3. No action needed

4. Historical Reports

5. REPORTS/ directory is historical documentation
6. Leave as-is for accuracy

Breaking Changes¶

None Expected ✅¶

Why: - All changes are additive (new env vars) - Defaults maintain current behavior - Existing deployments continue working without changes - Opt-in whitelabel configuration

Migration Path¶

For existing deployments: 1. No action required - defaults preserve current branding 2. To customize: Add new env vars to deployment config 3. Replace logo files in /static/img/ if desired

Testing Strategy¶

Unit Tests (Add to existing test suite)¶

# tests/unit/config/test_branding.py
def test_default_branding():
    """Verify default branding values"""
    settings = Settings()
    assert settings.CLIENT_NAME == "Slidefactory"
    assert settings.CLIENT_PRIMARY_COLOR == "#ee0000"

def test_custom_branding():
    """Verify custom branding via env vars"""
    # Test with mocked env vars
    pass

Integration Tests¶

1. Visual Regression: Screenshot tests for logo placement
2. Template Rendering: Verify settings context available
3. Color Validation: Test invalid color codes gracefully fail

Manual Testing Checklist¶

• Navigation logo displays correctly
• Login page logo displays correctly
• Chat widget logo displays correctly
• Primary color applied throughout UI
• Browser title shows correct CLIENT_NAME
• API docs show correct title
• PWA manifest updated correctly
• Test with missing logo files (fallback handling)
• Test with invalid color code (fallback handling)

Effort Breakdown¶

Total Estimated Time: 6-8 hours

Recommendations¶

✅ PROCEED - Recommended Implementation¶

Reasons: 1. High Value: Makes product more marketable and reusable 2. Low Risk: Mostly cosmetic changes, no core functionality affected 3. Clean Architecture: Leverages existing config system 4. Backward Compatible: Defaults maintain current behavior 5. Future-Proof: Easy to extend with more branding options

Implementation Order (Recommended)¶

Week 1: Core Implementation 1. Phase 1: Configuration (30 min) 2. Phase 2: Template Updates (2-3 hours) 3. Phase 3: App Title Updates (1 hour) 4. Initial testing (1 hour)

Week 2: Polish & Documentation 5. Phase 4: Asset Management (1-2 hours) 6. Phase 5: Documentation (1 hour) 7. Comprehensive testing (2 hours)

Optional Enhancements (Future)¶

1. Admin UI for Branding:
2. Web interface to upload logos
3. Color picker for primary color

4. Preview changes before applying

5. Multi-Tenant Branding:

6. Different branding per domain/subdomain
7. Database-stored branding configs

8. Per-customer customization

9. Advanced Theming:

10. Secondary/accent colors
11. Font family configuration

12. Custom CSS injection

13. Favicon Generation:

14. Auto-generate favicons from CLIENT_LOGO
15. PWA icon generation
16. Multiple size variants

Files to Modify (Summary)¶

Critical Path (Must Change)¶

1. ✅ app/config.py - Add branding settings
2. ✅ templates/includes/base.html.j2 - 2 logo refs + theme-color
3. ✅ app/auth/templates/signin.html.j2 - Login logo
4. ✅ app/chat/templates/n8n_chat_embedded.html.j2 - Chat logo + colors
5. ✅ static/css/chat_widget.css - CSS variable
6. ✅ app/main.py - FastAPI app title
7. ✅ templates/account.html.j2 - Page title

Secondary (Recommended)¶

1. ⚠️ static/site.webmanifest.json - PWA theme color
2. ⚠️ README.md - Generic branding in docs
3. ⚠️ BRANDING.md - Create new doc

Optional (Low Priority)¶

1. 📝 cli/main.py - CLI descriptions
2. 📝 setup.py - Package description
3. 📝 CLAUDE.md - AI assistant context

Leave Unchanged¶

• All REPORTS/*.md files (historical documentation)
• .git/config (internal git config)
• Logo files in static/img/ (archive originals, add defaults)

Conclusion¶

Verdict: GO FOR IT! 🚀

The whitelabel conversion is a low-risk, high-value enhancement that can be implemented in 6-8 focused hours. The architecture is already well-suited for this change with its centralized configuration system. The main work is straightforward template updates and asset management.

Key Success Factors: - ✅ Use sensible defaults (maintain current look) - ✅ Validate inputs (color codes, file paths) - ✅ Document requirements clearly - ✅ Test thoroughly with multiple branding configs - ✅ Provide example configurations

Next Steps: 1. Review and approve this assessment 2. Create implementation branch 3. Follow phased implementation plan 4. Test with at least 2 different branding configs 5. Document in BRANDING.md with examples 6. Deploy to preview environment first

Appendix: Example Configuration¶

Example 1: Company A¶

CLIENT_NAME="Acme Corp"
CLIENT_LOGO="/static/img/clients/acme/logo.png"
CLIENT_LOGO_LARGE="/static/img/clients/acme/logo_banner.png"
CLIENT_PRIMARY_COLOR="#007ACC"

Example 2: Company B¶

CLIENT_NAME="Global Solutions"
CLIENT_LOGO="/static/img/clients/global/logo.png"
CLIENT_LOGO_LARGE="/static/img/clients/global/logo_banner.png"
CLIENT_PRIMARY_COLOR="#2ECC71"

Example 3: Default (Sportfive)¶

CLIENT_NAME="Sportfive Slidefactory"
CLIENT_LOGO="/static/img/branding/sportfive_logo_red.png"
CLIENT_LOGO_LARGE="/static/img/branding/bannerlogo.png"
CLIENT_PRIMARY_COLOR="#ee0000"