Brands and Logos (Brandings)

Brandings are reusable presets of the corporate look & feel applied to every PDF that leaves the platform. Instead of pasting the logo and colors on every report, you configure a brand once and every report references it by branding_id. Changing the logo is a single click.

Executive summary

The game changer: one central brand preset — a client's report changes its look without touching the structure; the default brand applies automatically to everything the platform generates.

What is it for?

• Visual consistency — the monthly billing PDF has exactly the same header as the weekly maintenance report.
• Multi-client — a maintenance service provider keeps one branding per client with their own logo and colors.
• Painless rebrand — new corporate identity, one edit, everything inherits.
• Tenant default — if a report doesn't specify branding, the tenant default applies.

How it works

flowchart LR
  B[(brandings<br/>per-tenant)] -->|resolve by id| P[PDF generator]
  R1[On-demand report] --> P
  R2[Scheduled report] --> P
  R3[AI agent generates PDF] --> P
  P --> F[PDF with header/footer/<br/>logo/colors]

Every report has two ways to specify branding:

1. branding_id — references a saved preset. Takes precedence.
2. Inline branding — dict with the same fields, not saved as a preset.

If neither, the branding with is_default=true for the tenant is used (if any).

Branding parameters

How to use it

Create a branding

1. Administration → Brands and Logos → New.
2. Name it ("North Client").
3. Upload the logo (PNG/JPG, max 2 MB — ideal 300×100 px).
4. Set the company name that renders next to the logo.
5. (Optional) Add header lines — one per line: division, phone, website.
6. (Optional) Right text — e.g. "Confidential — do not distribute".
7. Pick header and footer colors. The editor shows a live preview.
8. (Optional) Accent color for table headers.
9. Pick the font (Courier, Helvetica or Times).
10. (Optional) Mark it as tenant default.
11. Save.

The branding is ready to be referenced by reports.

Use a branding in a report

In an on-demand report:

• Open the report editor.
• In the Branding selector, pick the saved preset.
• Generate. The PDF comes out with that look.

In a scheduled report:

• Edit the scheduled report.
• Select the branding in the Branding field.
• The next execution applies it.

From an AI agent:

• A WhatsApp or email agent that generates reports can receive a branding_id in its defaults. When generating, the PDF comes out with that brand. Useful if the same agent serves multiple clients with different brands.

Mark as default

The branding with is_default=true is applied automatically to any report that doesn't specify branding_id or inline branding. Only one default per tenant is allowed — marking a new one automatically unmarks the previous one.

REST endpoints

POST   /api/v1/brandings          # create
GET    /api/v1/brandings          # list
GET    /api/v1/brandings/{id}     # detail
PATCH  /api/v1/brandings/{id}     # update
DELETE /api/v1/brandings/{id}     # delete

Use cases

1 · Multi-client service provider. Company doing maintenance for 12 different plants. Every client has their branding saved: logo, corporate color, footer with contract number. Every client's monthly report references its branding_id. Client C gets their PDF with their brand; client D with theirs. Zero design work.

2 · Corporate rebrand. The company changes visual identity. New logo, new palette. Instead of editing 15 report templates: edit the "Corporate" branding and save. Next week every scheduled report ships with the new brand.

3 · Tenant default + a special case. The tenant has a "Standard" branding flagged as default: applies to every on-demand and scheduled report. One specific report — the annual audit for the hero client — carries its own branding_id with the co-branded logo. Everything else inherits the default without configuring anything.

Limits and assumptions

• One branding per tenant can be is_default. Marking a new one automatically unmarks the previous one.
• The logo must be public — the PDF generator fetches the logo_url over HTTP. If the logo is behind auth or in a private bucket, the report ships without a logo. Upload to public GCS or a CDN.
• 6-digit hex colors. #FFF (3 digits) or red (name) don't validate. Use #FFFFFF.
• No gradients or background images. Solid colors only. For a graphical header, the logo is the only visual component.
• Font families limited to 3. Courier / Helvetica / Times. No custom fonts — these are the fpdf2 standards to guarantee compatibility with any PDF reader.
• Logo size: no automatic validation. Very large PNGs bloat the PDF without improving quality. Ideal is 300×100 px optimised.

Key benefits

• One central preset → automatic visual consistency on every PDF.
• Rebrand in seconds — edit the branding, all future reports inherit.
• Multi-client without effort — one branding per client, branding_id selects.
• Tenant default removes trivial decisions when configuring a new report.
• Live preview in the editor — you see header/footer while setting up.
• Compatible with on-demand reports, scheduled reports, and AI-agent-generated reports.