White-Label Branding Strategy in DeskcommCRM: How to Remove "Deskcomm" from the UI

DeskcommCRM implements a configuration-first, code-free branding approach that uses environment variables and database-stored settings to replace the "Deskcomm" name at runtime, enforced by automated tests that scan the codebase for any literal string matches.

DeskcommCRM (melgarafael/DeskcommCRM) is architected specifically for agencies and resellers who must sell the platform under their own identity. The white-label branding strategy ensures that the original product name never appears in the end-user interface through runtime configuration, tenant-specific database overrides, and strict code-level guards.

Configuration-First Branding Architecture

The platform separates branding into three distinct layers: installation defaults, per-organization overrides, and admin-controlled global settings. This hierarchy ensures that a single Docker image can serve any reseller without rebuilding.

Environment-Based Installation Defaults

The foundation of the strategy rests on three environment variables defined in lib/env.ts (see the comment at approximately line 332): APP_NAME, APP_LOGO_URL, and APP_ACCENT_HEX. These values serve as fallback defaults when no tenant-specific brand exists. By externalizing the brand identity to the environment, the compiled Docker image remains completely generic and reusable across multiple resellers.

Per-Organization Brand Customization

Each tenant can override installation defaults through the settings UI at /app/settings/marca. The interface, implemented in app/app/settings/marca/page.tsx, persists brand values—name, color, and logo—to the organizations.settings.branding database table. After authentication, these settings take precedence over environment variables, allowing multi-tenant deployments where each organization maintains a distinct visual identity without affecting others.

Admin-Level Global Brand Control

For installation-wide branding used on public-facing login screens and system emails, administrators modify settings at /admin/marca via app/admin/marca/page.tsx. Changes persist immediately to the database and take effect without container restarts, ensuring zero-downtime rebranding across the entire instance.

Code-Level Enforcement Mechanisms

To prevent accidental leakage of the original product name, the codebase implements automated scanning and centralized helper functions that abstract all brand references.

Automated "Deskcomm" String Detection

The file tests/unit/branding.test.ts contains a unit test that executes a recursive grep across the entire source tree—including app, components, lib, workers, and hooks—searching for the literal string "Deskcomm". The test fails if any occurrence is found, creating a CI/CD gate that prevents developers from hard-coding the original brand into new features or components.

Brand-Aware Helper Functions

All UI components consume branding through centralized helpers in lib/branding/* rather than accessing environment variables directly. The lib/branding/icone.ts module provides the BrandIcon component that resolves logos from either the database or environment sources, while lib/branding/saida.ts exports marcaDaSaida() and the useBrandAccent() hook for retrieving brand names and CSS hex colors dynamically.

Runtime Injection Strategy

The brand identity is never compiled into the Docker image; instead, it is injected at runtime from either the database (preferred) or the .env file (fallback). This prevents the "Deskcomm" name from leaking after system upgrades, as image replacements do not overwrite stored branding data.

Email Template Synchronization

Email branding for account verification and password reset flows synchronizes with Supabase templates through hostgator-setup-kit/marca-emails.sh. This script, invoked automatically by install.sh and update.sh, propagates the APP_NAME and APP_LOGO_URL environment variables into transactional email layouts at deployment time.

Documented Exceptions

Certain artefacts intentionally retain the original product name due to legal constraints or operational requirements outside reseller control. According to docs/white-label.md, LGPD PDF reports and AI budget alarms specifically exclude white-labeling—these limitations are documented in the sections "O relatório de LGPD é a única coisa que NÃO leva a sua marca" and "O alarme de orçamento de IA".

Implementation Examples

The following patterns demonstrate how to consume branding safely without hard-coded strings:

/* Reading the current accent color */
import { useBrandAccent } from '@/lib/branding/saida';
const accent = useBrandAccent();   // returns a CSS hex color

/* Rendering the brand logo */
import { BrandIcon } from '@/lib/branding/icone';
function Header() {
  return (
    <header className="flex items-center">
      <BrandIcon size={32} />   {/* reads logo from DB or .env */}
      <h1 className="ml-2">{process.env.APP_NAME}</h1>
    </header>
  );
}

/* Changing the brand via admin UI (React Server Action) */
async function updateBrand(formData: FormData) {
  'use server';
  await fetch('/admin/marca', {
    method: 'POST',
    body: formData,
  });
}

/* The guard test that prevents "Deskcomm" leaks */
import { execSync } from 'child_process';
test('guarda de white-label (self-host)', () => {
  const result = execSync('pnpm exec grep -R "Deskcomm" .', { encoding: 'utf8' });
  expect(result).toBe('');
});

Summary

• Environment variables (APP_NAME, APP_LOGO_URL, APP_ACCENT_HEX) in lib/env.ts provide installation-wide fallback branding
• Per-organization branding persists to organizations.settings.branding and overrides defaults via app/app/settings/marca/page.tsx
• Admin global branding controls public login screens through app/admin/marca/page.tsx without requiring container restarts
• Automated enforcement via tests/unit/branding.test.ts greps the entire source tree to block "Deskcomm" literals from being committed
• UI abstraction through lib/branding/icone.ts and lib/branding/saida.ts ensures components never contain hard-coded brand strings
• Email synchronization occurs via hostgator-setup-kit/marca-emails.sh during installation and update routines
• Documented exceptions in docs/white-label.md identify LGPD reports and AI budget alarms as non-configurable artefacts

Frequently Asked Questions

How does DeskcommCRM prevent the original brand name from appearing in error messages or UI components?

The repository uses tests/unit/branding.test.ts to execute a recursive search for the literal string "Deskcomm" across all source directories. If the test detects any occurrences, the CI pipeline fails immediately. Additionally, all UI components must import branding data from lib/branding/* helpers rather than defining static strings, ensuring that no hard-coded references survive code review.

Can I change the brand identity without rebuilding the Docker image?

Yes. Because the brand is injected at runtime from the database or .env file, you can update the installation-wide brand via the /admin/marca UI or modify environment variables and restart the container. The underlying Docker image remains unchanged, allowing the same build artifact to serve unlimited resellers with distinct identities.

Where are the brand settings stored for individual organizations?

Per-organization brand values—including custom names, hex color codes, and logo URLs—are stored in the organizations.settings.branding table. The application reads these settings after user authentication via app/app/settings/marca/page.tsx, overriding the environment defaults defined in lib/env.ts for that specific tenant session.

Why do some system reports still display the Deskcomm name?

According to docs/white-label.md, certain artefacts deliberately retain the original product name due to external constraints. LGPD PDF reports and AI budget alarms are explicitly excluded from white-labeling because they involve legal compliance documentation or operational alerts outside the reseller's control, as noted in the sections "O relatório de LGPD" and "O alarme de orçamento de IA".

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}