Merge pull request #1272 from Tria-plc/eims-integration

feat(freight): add company logo setting applied to every generated do…
2026-08-27 21:20:57 +00:00 · 2026-08-13 13:56:45 +03:00
parent 63b40ea4f8 c4bf3c9479
commit 1088b47029
31 changed files with 800 additions and 8 deletions
--- a/apps/edr-freight-api/src/app.module.ts
+++ b/apps/edr-freight-api/src/app.module.ts
@@ -49,6 +49,7 @@ import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-up
 import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
 import { ExchangeSettingsModule } from "./modules/exchange-settings/exchange-settings.module";
 import { StampSettingsModule } from "./modules/stamp-settings/stamp-settings.module";
+import { LogoSettingsModule } from "./modules/logo-settings/logo-settings.module";
 import { ContractTemplatesModule } from "./modules/contract-templates/contract-templates.module";
 import { SupportContentModule } from "./modules/support-content/support-content.module";
 import { OtpModule } from "./modules/otp/otp.module";
@@ -209,6 +210,7 @@ if (!process.env.APPLICATION_NAME) {
    DropdownSettingsModule,
    ExchangeSettingsModule,
    StampSettingsModule,
+    LogoSettingsModule,
    ContractTemplatesModule,
    SupportContentModule,
    OtpModule,
--- a/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
+++ b/apps/edr-freight-api/src/contracts/contract-view-model.builder.ts
@@ -10,6 +10,7 @@ import { ContractPricingScheduleBuilder, PricingSchedule } from './contract-pric
 import { ContractRateScheduleBuilder, RateSchedule } from './contract-rate-schedule.builder';
 import { ContractTemplateResolver } from './contract-template.resolver';
 import { StampSettingsService } from '../modules/stamp-settings/stamp-settings.service';
+import { LogoSettingsService } from '../modules/logo-settings/logo-settings.service';
 import { ContractTemplateMeta, getTemplateMeta } from './contract-template.registry';

 export interface ContractSignatureView {
@@ -111,6 +112,8 @@ export interface ContractViewModel {
  hasCustomerSignature: boolean;
  hasStaffSignature: boolean;
  dynamicTemplate?: ContractDynamicTemplateView;
+  /** Company logo for the cover-page header (LogoSettingsService); null renders the "EDR" mark. */
+  logoImageUrl?: string | null;
 }

@Injectable()
@@ -121,6 +124,7 @@ export class ContractViewModelBuilder {
    private readonly pricingBuilder: ContractPricingScheduleBuilder,
    private readonly rateScheduleBuilder: ContractRateScheduleBuilder,
    private readonly stampSettings: StampSettingsService,
+    private readonly logoSettings: LogoSettingsService,
  ) {}

  async build(bookingId: string): Promise<{ booking: Booking; view: ContractViewModel }> {
@@ -138,6 +142,7 @@ export class ContractViewModelBuilder {
      template.freight,
    );
    const signatures = await this.loadSignatures(bookingId);
+    const logoImageUrl = await this.logoSettings.getLogoImageUrl();

    const hasCustomer = signatures.some((s) => s.role === 'CUSTOMER');
    const hasStaff = signatures.some((s) => s.role === 'STAFF');
@@ -194,6 +199,7 @@ export class ContractViewModelBuilder {
      hasContractDocument: hasContractFile,
      hasCustomerSignature: hasCustomer,
      hasStaffSignature: hasStaff,
+      logoImageUrl,
    };

    return { booking, view };
--- a/apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs
@@ -77,6 +77,12 @@
    letter-spacing: 0.08em;
    width: 72px;
  }
+  .logo-mark img {
+    display: block;
+    max-height: 100%;
+    max-width: 100%;
+    object-fit: contain;
+  }
  .kicker {
    color: #0e5b45;
    font-family: Arial, sans-serif;
--- a/apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs
@@ -11,7 +11,7 @@
    {{!-- ─────────────────────────── Cover page ─────────────────────────── --}}
    <section class="cover page-section">
      <div class="brand-row">
-        <div class="logo-mark">EDR</div>
+        <div class="logo-mark">{{#if logoImageUrl}}<img src="{{logoImageUrl}}" alt="Company logo" />{{else}}EDR{{/if}}</div>
        <div>
          <p class="kicker">Ethio-Djibouti Standard Gauge Railway Share Company</p>
          <p class="muted">Freight Transport Services</p>
--- a/apps/edr-freight-api/src/contracts/templates/generic.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/generic.hbs
@@ -9,7 +9,7 @@
  <main class="contract">
    <section class="cover page-section">
      <div class="brand-row">
-        <div class="logo-mark">EDR</div>
+        <div class="logo-mark">{{#if logoImageUrl}}<img src="{{logoImageUrl}}" alt="Company logo" />{{else}}EDR{{/if}}</div>
        <div>
          <p class="kicker">Ethio-Djibouti Standard Gauge Railway Share Company</p>
          <p class="muted">Freight Transport Contract</p>
--- a/apps/edr-freight-api/src/contracts/templates/last-mile.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/last-mile.hbs
@@ -9,6 +9,7 @@
    main { padding: 32px 40px; }
    .brand-row { display: flex; align-items: center; gap: 14px; border-bottom: 3px solid #1a5632; padding-bottom: 14px; }
    .logo-mark { background: #1a5632; color: #fff; font-weight: 700; font-size: 18px; padding: 10px 14px; border-radius: 6px; }
+    .logo-mark img { display: block; max-height: 32px; max-width: 100px; object-fit: contain; }
    .kicker { margin: 0; font-weight: 700; }
    .muted { margin: 0; color: #666; }
    h1 { font-size: 20px; margin: 24px 0 4px; }
@@ -32,7 +33,7 @@
 <body>
  <main>
    <div class="brand-row">
-      <div class="logo-mark">EDR</div>
+      <div class="logo-mark">{{#if logoImageUrl}}<img src="{{logoImageUrl}}" alt="Company logo" />{{else}}EDR{{/if}}</div>
      <div>
        <p class="kicker">Ethio-Djibouti Standard Gauge Railway Share Company</p>
        <p class="muted">Last-Mile Delivery Contract</p>
--- a/apps/edr-freight-api/src/migrations/3500000000000-LogoSettings.ts
+++ b/apps/edr-freight-api/src/migrations/3500000000000-LogoSettings.ts
@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Single-row table holding the one company logo image stamped onto every
+ * generated document (see LogoSettingsService). Same single-row shape as
+ * stamp_settings; the app never inserts more than one row.
+ */
+export class LogoSettings3500000000000 implements MigrationInterface {
+  name = "LogoSettings3500000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.logo_settings (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        logo_file_id uuid REFERENCES freight.files(id),
+        updated_by_id uuid,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      );
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.logo_settings;`);
+  }
+}
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts
@@ -14,7 +14,7 @@ const model = (over: Partial<InvoiceDocumentModel> = {}): InvoiceDocumentModel =
 });

 describe("InvoiceDocumentService.buildHtml — EIMS QR", () => {
-  const service = new InvoiceDocumentService({} as never, {} as never);
+  const service = new InvoiceDocumentService({} as never, {} as never, {} as never);

  it("renders no QR block when qrImageUrl is unset", () => {
    const html = service.buildHtml(model());
--- a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -1,8 +1,10 @@
 import { Injectable } from "@nestjs/common";

 import { StampSettingsService } from "../../stamp-settings/stamp-settings.service";
+import { LogoSettingsService } from "../../logo-settings/logo-settings.service";
 import { PdfRenderService } from "./pdf-render.service";
 import { sealClass, sealImageCss, sealMarkup } from "./seal-markup.util";
+import { logoImageCss, logoMarkup } from "./logo-markup.util";
 import {
  PdfColor,
  assembleSinglePagePdf,
@@ -62,6 +64,7 @@ export interface InvoiceDocumentModel {
   * explicitly only to override that default for one document.
   */
  stampImageUrl?: string | null;
+  logoImageUrl?: string | null;
  /**
   * MoR EIMS verification QR (data URL, pre-rendered by the caller from `Invoice.eimsSignedQr` —
   * see that column's comment). Set only once an invoice is actually registered; the IRN text
@@ -81,6 +84,7 @@ export class InvoiceDocumentService {
  constructor(
    private readonly pdf: PdfRenderService,
    private readonly stampSettings: StampSettingsService,
+    private readonly logoSettings: LogoSettingsService,
  ) {}

  async render(
@@ -90,7 +94,11 @@ export class InvoiceDocumentService {
      model.stampImageUrl !== undefined
        ? model.stampImageUrl
        : await this.stampSettings.getStampImageUrl();
-    const resolvedModel: InvoiceDocumentModel = { ...model, stampImageUrl };
+    const logoImageUrl =
+      model.logoImageUrl !== undefined
+        ? model.logoImageUrl
+        : await this.logoSettings.getLogoImageUrl();
+    const resolvedModel: InvoiceDocumentModel = { ...model, stampImageUrl, logoImageUrl };

    const html = this.buildHtml(resolvedModel);
    const kindLabel = model.kind === "RECEIPT" ? "receipt" : "invoice";
@@ -250,6 +258,7 @@ export class InvoiceDocumentService {
      model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
    const sealInner = sealMarkup(model.stampImageUrl, sealText);
    const sealCssClass = sealClass(model.stampImageUrl);
+    const logoInner = logoMarkup(model.logoImageUrl);

    const qrMarkup = model.qrImageUrl
      ? `<div class="qr"><img src="${esc(model.qrImageUrl)}" alt="EIMS verification QR" /><span>Scan to verify (MoR EIMS)</span></div>`
@@ -293,6 +302,7 @@ export class InvoiceDocumentService {
    .meta strong { display: block; color: #0f172a; font-size: 17px; margin-top: 5px; }
    .seal { position: absolute; right: 28px; top: 118px; width: 116px; height: 116px; border: 4px double #0f766e; border-radius: 999px; color: #0f766e; display: flex; align-items: center; justify-content: center; text-align: center; font-weight: 800; font-size: 18px; transform: rotate(-14deg); opacity: .82; }
    ${sealImageCss()}
+    ${logoImageCss()}
    .qr { position: absolute; right: 160px; top: 118px; width: 90px; text-align: center; }
    .qr img { width: 90px; height: 90px; }
    .qr span { display: block; font-size: 7px; color: #64748b; margin-top: 3px; }
@@ -322,6 +332,7 @@ export class InvoiceDocumentService {
  <div class="doc">
    <div class="top">
      <div>
+        ${logoInner}
        <div class="brand">Ethio-Djibouti Railway S.C.</div>
        <h1>${esc(model.title)} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}</h1>
      </div>
--- a/apps/edr-freight-api/src/modules/billing/documents/logo-markup.util.ts
+++ b/apps/edr-freight-api/src/modules/billing/documents/logo-markup.util.ts
@@ -0,0 +1,35 @@
+/**
+ * The single decision every EDR document makes about its header logo: draw
+ * the one uploaded company logo when configured (LogoSettingsService), or
+ * render nothing — the existing "Ethio-Djibouti Railway S.C." text brand next
+ * to it already covers the no-logo case, so there is no text fallback here
+ * (contrast seal-markup.util.ts, whose seal has no text of its own).
+ */
+
+function escapeHtml(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * `<img>` markup for the header logo, or "" when unset. `logoImageUrl` is
+ * expected to be a data URL from LogoSettingsService.getLogoImageUrl().
+ * `className` defaults to "doc-logo" — each document supplies that class's
+ * sizing in its own <style> block (see logoImageCss()).
+ */
+export function logoMarkup(
+  logoImageUrl: string | null | undefined,
+  className = "doc-logo",
+): string {
+  if (!logoImageUrl) return "";
+  return `<img class="${className}" src="${escapeHtml(logoImageUrl)}" alt="Company logo" />`;
+}
+
+/** Default CSS for the header logo — append inside a document's <style> block. */
+export function logoImageCss(className = "doc-logo"): string {
+  return `.${className} { display: block; max-height: 48px; max-width: 180px; margin-bottom: 6px; object-fit: contain; }`;
+}
--- a/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-contract.service.ts
+++ b/apps/edr-freight-api/src/modules/last-mile-requests/last-mile-contract.service.ts
@@ -13,6 +13,7 @@ import { FilesService } from '../files/files.service';
 import { FileRecord } from '../files/entities/file.entity';
 import { MinioService } from '../minio/minio.service';
 import { SignaturesService } from '../signatures/signatures.service';
+import { LogoSettingsService } from '../logo-settings/logo-settings.service';
 import { SignLastMileContractDto } from './dto/sign-last-mile-contract.dto';
 import { LastMileRequest } from './entities/last-mile-request.entity';
 import { LastMileRequestsRepository } from './last-mile-requests.repository';
@@ -41,6 +42,7 @@ export class LastMileContractService {
    private readonly pdfService: ContractPdfService,
    private readonly signaturesService: SignaturesService,
    private readonly dataSource: DataSource,
+    private readonly logoSettings: LogoSettingsService,
  ) {}

  async getContractView(id: string, viewerUserId?: string | null) {
@@ -194,6 +196,7 @@ export class LastMileContractService {
    return {
      companyName: booking.company?.name ?? 'Customer',
      bookingReference: booking.reference ?? request.bookingId,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
      containerCount: containers.length || null,
      containerList: containers.join(', '),
      cargoDescription,
--- a/apps/edr-freight-api/src/modules/logo-settings/dto/update-logo-setting.dto.ts
+++ b/apps/edr-freight-api/src/modules/logo-settings/dto/update-logo-setting.dto.ts
@@ -0,0 +1,9 @@
+import { ApiProperty } from "@nestjs/swagger";
+import { IsString, MinLength } from "class-validator";
+
+export class UpdateLogoSettingDto {
+  @ApiProperty({ description: "Logo image as a base64 data URL (PNG/JPG)." })
+  @IsString()
+  @MinLength(1)
+  logoImageBase64!: string;
+}
--- a/apps/edr-freight-api/src/modules/logo-settings/entities/logo-setting.entity.ts
+++ b/apps/edr-freight-api/src/modules/logo-settings/entities/logo-setting.entity.ts
@@ -0,0 +1,25 @@
+import { BaseEntity } from "@edr/api-common";
+import { Column, Entity, JoinColumn, ManyToOne } from "typeorm";
+
+import { FileRecord } from "../../files/entities/file.entity";
+
+/**
+ * Single-row table holding the one company logo image stamped onto every
+ * generated document (invoices/receipts, contracts, warehouse papers,
+ * train-scheduling manifests, payment receipts). Same single-row shape as
+ * stamp_settings — `get()` lazily creates the row, and there is never more
+ * than one.
+ */
+@Entity({ schema: "freight", name: "logo_settings" })
+export class LogoSetting extends BaseEntity {
+  @Column({ name: "logo_file_id", type: "uuid", nullable: true })
+  logoFileId?: string | null;
+
+  @ManyToOne(() => FileRecord, { nullable: true })
+  @JoinColumn({ name: "logo_file_id" })
+  logoFile?: FileRecord | null;
+
+  /** IAM user id of the last operator to set/clear the logo. */
+  @Column({ name: "updated_by_id", type: "uuid", nullable: true })
+  updatedById?: string | null;
+}
--- a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.controller.ts
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.controller.ts
@@ -0,0 +1,39 @@
+import { Body, Controller, Delete, Get, Put } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import { CurrentUser } from "@edr/api-common";
+import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
+
+import { BookingStaff } from "../../common/booking-guards";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
+import { UpdateLogoSettingDto } from "./dto/update-logo-setting.dto";
+import { LogoSettingsService } from "./logo-settings.service";
+
+@ApiTags("logo-settings")
+@ApiBearerAuth()
+@Controller("logo-settings")
+export class LogoSettingsController {
+  constructor(private readonly service: LogoSettingsService) {}
+
+  @Get()
+  @BookingStaff([FREIGHT_PERMS.settings.logo.view, FREIGHT_PERMS.admin])
+  @ApiOperation({ summary: "Current company logo used on every generated document" })
+  get() {
+    return this.service.getView();
+  }
+
+  @Put()
+  @BookingStaff([FREIGHT_PERMS.settings.logo.manage, FREIGHT_PERMS.admin])
+  @ApiOperation({ summary: "Replace the company logo" })
+  update(@Body() dto: UpdateLogoSettingDto, @CurrentUser() user: TCurrentUser) {
+    return this.service.setLogo(dto.logoImageBase64, user?.id ?? null);
+  }
+
+  @Delete()
+  @BookingStaff([FREIGHT_PERMS.settings.logo.manage, FREIGHT_PERMS.admin])
+  @ApiOperation({
+    summary: "Clear the company logo (documents fall back to their text mark)",
+  })
+  clear(@CurrentUser() user: TCurrentUser) {
+    return this.service.clearLogo(user?.id ?? null);
+  }
+}
--- a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.module.ts
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.module.ts
@@ -0,0 +1,24 @@
+import { Global, Module } from "@nestjs/common";
+import { TypeOrmModule } from "@nestjs/typeorm";
+
+import { FilesModule } from "../files/files.module";
+import { MinioModule } from "../minio/minio.module";
+import { LogoSetting } from "./entities/logo-setting.entity";
+import { LogoSettingsController } from "./logo-settings.controller";
+import { LogoSettingsRepository } from "./logo-settings.repository";
+import { LogoSettingsService } from "./logo-settings.service";
+
+/**
+ * Global so every document-generating module (billing, contracts,
+ * warehouses, train-scheduling, payment) can inject {@link LogoSettingsService}
+ * without pulling in a circular dependency — same reasoning as
+ * StampSettingsModule.
+ */
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([LogoSetting]), FilesModule, MinioModule],
+  controllers: [LogoSettingsController],
+  providers: [LogoSettingsRepository, LogoSettingsService],
+  exports: [LogoSettingsService],
+})
+export class LogoSettingsModule {}
--- a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.repository.ts
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.repository.ts
@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+import { BaseRepository } from "@edr/api-common";
+
+import { LogoSetting } from "./entities/logo-setting.entity";
+
+@Injectable()
+export class LogoSettingsRepository extends BaseRepository<LogoSetting> {
+  constructor(
+    @InjectRepository(LogoSetting)
+    repo: Repository<LogoSetting>,
+  ) {
+    super(repo);
+  }
+
+  /** The single settings row, with its logo file joined, or null before first upload. */
+  findSingleton(): Promise<LogoSetting | null> {
+    return this.repository.findOne({ where: {}, relations: ["logoFile"] });
+  }
+}
--- a/apps/edr-freight-api/src/modules/logo-settings/logo-settings.service.ts
+++ b/apps/edr-freight-api/src/modules/logo-settings/logo-settings.service.ts
@@ -0,0 +1,161 @@
+import { Injectable, Logger } from "@nestjs/common";
+import { Readable } from "stream";
+import { DataSource } from "typeorm";
+
+import { FilesService } from "../files/files.service";
+import { FileRecord } from "../files/entities/file.entity";
+import { MinioService } from "../minio/minio.service";
+import { LogoSettingsRepository } from "./logo-settings.repository";
+import { LogoSetting } from "./entities/logo-setting.entity";
+
+export interface LogoSettingView {
+  logoImageUrl: string | null;
+  updatedById: string | null;
+  updatedAt: Date | null;
+}
+
+/**
+ * Owns the single `logo_settings` row: the one company logo image used on
+ * every generated document. Same single-row shape as StampSettingsService,
+ * the value is an uploaded image (via FilesService) rather than a scalar.
+ */
+@Injectable()
+export class LogoSettingsService {
+  private readonly logger = new Logger(LogoSettingsService.name);
+
+  constructor(
+    private readonly repository: LogoSettingsRepository,
+    private readonly filesService: FilesService,
+    private readonly minioService: MinioService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  /** The settings row, created empty on first access. */
+  async get(): Promise<LogoSetting> {
+    const existing = await this.repository.findSingleton();
+    if (existing) return existing;
+    return this.repository.create({ logoFileId: null, updatedById: null });
+  }
+
+  /** Current logo, with the image inlined as a data URL (or null if unset). */
+  async getView(): Promise<LogoSettingView> {
+    const setting = await this.get();
+    return {
+      logoImageUrl: await this.inlineImageUrl(setting.logoFile?.url),
+      updatedById: setting.updatedById ?? null,
+      updatedAt: setting.updatedAt ?? null,
+    };
+  }
+
+  /**
+   * The logo image for embedding into generated documents, ALWAYS as a
+   * `data:` URL or null. Never throws — document generation must succeed even
+   * if the logo lookup fails; callers render their existing text/mark
+   * fallback on null (see logo-markup.util.ts).
+   */
+  async getLogoImageUrl(): Promise<string | null> {
+    try {
+      const setting = await this.get();
+      const inlined = await this.inlineImageUrl(setting.logoFile?.url);
+      if (inlined && !inlined.startsWith("data:")) {
+        this.logger.warn(
+          `Company logo could not be inlined for document rendering (falling back to the text mark): ${inlined}`,
+        );
+        return null;
+      }
+      return inlined;
+    } catch (err) {
+      this.logger.warn(
+        `Could not load company logo for PDF rendering: ${(err as Error).message}`,
+      );
+      return null;
+    }
+  }
+
+  /** Replace the logo image, storing it in MinIO via FilesService. */
+  async setLogo(
+    logoImageBase64: string,
+    updatedById?: string | null,
+  ): Promise<LogoSettingView> {
+    const current = await this.get();
+    const previousFileId = current.logoFileId ?? null;
+
+    const fileRecord = await this.filesService.upload({
+      resourceId: current.id,
+      resource: "logo_settings",
+      code: "logo",
+      file: this.toUploadFile(logoImageBase64),
+      uploadedByUserId: updatedById ?? null,
+    });
+
+    await this.repository.update(current.id, {
+      logoFileId: fileRecord.id,
+      updatedById: updatedById ?? null,
+    });
+
+    if (previousFileId && previousFileId !== fileRecord.id) {
+      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
+    }
+
+    this.logger.log(`Company logo updated by ${updatedById ?? "unknown user"}`);
+    return this.getView();
+  }
+
+  /** Clear the logo (documents fall back to their text/mark). */
+  async clearLogo(updatedById?: string | null): Promise<LogoSettingView> {
+    const current = await this.get();
+    const previousFileId = current.logoFileId ?? null;
+
+    await this.repository.update(current.id, {
+      logoFileId: null,
+      updatedById: updatedById ?? null,
+    });
+
+    if (previousFileId) {
+      await this.dataSource.getRepository(FileRecord).delete(previousFileId);
+    }
+
+    return this.getView();
+  }
+
+  private toUploadFile(base64: string): Express.Multer.File {
+    const raw = base64.includes(",") ? base64.split(",")[1]! : base64;
+    const buffer = Buffer.from(raw, "base64");
+    return {
+      fieldname: "logo",
+      originalname: "company-logo.png",
+      encoding: "7bit",
+      mimetype: "image/png",
+      size: buffer.length,
+      buffer,
+      stream: Readable.from(buffer),
+      destination: "",
+      filename: "",
+      path: "",
+    };
+  }
+
+  private async inlineImageUrl(url?: string | null): Promise<string | null> {
+    if (!url) return null;
+    if (url.startsWith("data:")) return url;
+    try {
+      const objectName = this.minioService.getObjectNameFromUrl(url);
+      const stream = await this.minioService.getFileStream(objectName);
+      const buffer = await this.streamToBuffer(stream);
+      return `data:image/png;base64,${buffer.toString("base64")}`;
+    } catch {
+      return url;
+    }
+  }
+
+  private streamToBuffer(stream: Readable): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      stream.on("data", (chunk: Buffer | string) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      stream.on("error", reject);
+      stream.on("end", () => resolve(Buffer.concat(chunks)));
+    });
+  }
+}
--- a/apps/edr-freight-api/src/modules/payment/payment.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.spec.ts
@@ -49,6 +49,7 @@ describe("PaymentService.confirmOtp", () => {
      repo as never,
      client as never,
      billing as never,
+      {} as never,
    );
    return { service, repo, billing };
  };
@@ -197,6 +198,7 @@ describe("PaymentService.markIntentSucceeded", () => {
      repo as never,
      {} as never,
      billing as never,
+      {} as never,
    );
    return { service, repo, billing };
  };
--- a/apps/edr-freight-api/src/modules/payment/payment.service.ts
+++ b/apps/edr-freight-api/src/modules/payment/payment.service.ts
@@ -13,6 +13,7 @@ import { PaymentEntity } from "./entities/payment.entity";
 import { PaymentRepository } from "./payment.repository";
 import { PaymentClientService } from "./payment-client.service";
 import { BillingService } from "../billing/billing.service";
+import { LogoSettingsService } from "../logo-settings/logo-settings.service";

 import * as fs from "fs";
 import * as path from "path";
@@ -104,6 +105,7 @@ export class PaymentService {
    private readonly paymentClient: PaymentClientService,
    @Inject(forwardRef(() => BillingService))
    private readonly billing: BillingService,
+    private readonly logoSettings: LogoSettingsService,
  ) { }

  async getAll(filters: {
@@ -657,6 +659,7 @@ export class PaymentService {
      total: payment.amount.toString(),
      currency: payment.currency,
      reason: payment.reason,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
    });
  }

--- a/apps/edr-freight-api/src/modules/payment/templates/receipt.hbs
+++ b/apps/edr-freight-api/src/modules/payment/templates/receipt.hbs
@@ -45,6 +45,14 @@
            margin: 0;
        }

+        .header .doc-logo {
+            display: block;
+            margin: 0 auto 10px;
+            max-height: 48px;
+            max-width: 180px;
+            object-fit: contain;
+        }
+
        .details-table {
            width: 100%;
            border-collapse: collapse;
@@ -126,6 +134,7 @@
 <body>
    <div class="receipt-box">
        <div class="header">
+            {{#if logoImageUrl}}<img class="doc-logo" src="{{logoImageUrl}}" alt="Company logo" />{{/if}}
            <h1>{{vendorName}}</h1>
            <p>{{vendorAddress}}</p>
        </div>
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.spec.ts
@@ -181,6 +181,7 @@ describe('TrainSchedulingService', () => {
        autoArriveAtFinalYard: jest.fn().mockResolvedValue([]),
      } as never, // bookingJourneyService
      { dispatched: jest.fn(), arrived: jest.fn() } as never, // bookingNotifier
+      { getLogoImageUrl: jest.fn().mockResolvedValue(null) } as never, // logoSettings
    );

    const defaultFleetWagons = [
--- a/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
+++ b/apps/edr-freight-api/src/modules/train-scheduling/services/train-scheduling.service.ts
@@ -177,6 +177,8 @@ import { RouteMilestone } from '../../routes/entities/route-milestone.entity';
 import { deriveTradeDirection } from '../../../common/derive-trade-direction.util';
 import { WarehouseInventoryService } from '../../warehouses/warehouse-inventory.service';
 import { WarehouseReleaseDocumentService } from '../../warehouses/warehouse-release-document.service';
+import { LogoSettingsService } from '../../logo-settings/logo-settings.service';
+import { logoImageCss, logoMarkup } from '../../billing/documents/logo-markup.util';
 import {
  autoFillPlacements,
  findMissingContainerNumberIssues,
@@ -376,6 +378,7 @@ export class TrainSchedulingService {
    private readonly bookingWindowGateway: BookingWindowGateway,
    private readonly bookingJourneyService: BookingJourneyService,
    private readonly bookingNotifier: BookingNotifierService,
+    private readonly logoSettings: LogoSettingsService,
    @Optional() private readonly milestoneService?: ClearanceMilestoneService,
    private readonly configService?: ConfigService,
    // forwardRef: BookingBatchService injects this service back; @Optional so
@@ -3025,7 +3028,7 @@ export class TrainSchedulingService {
    const loadList = await this.generateImportLoadList(scheduleId, {
      performedBy: 'DOCUMENT_GENERATION',
    });
-    const html = this.buildImportLoadListHtml(loadList);
+    const html = this.buildImportLoadListHtml(loadList, await this.logoSettings.getLogoImageUrl());
    // Styled table-aware fallback (marshalling grid) when Chromium is unavailable —
    // NOT the release-order fallback (would mislabel this as a gate-clearance order).
    const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Import marshalling / load list');
@@ -3045,7 +3048,9 @@ export class TrainSchedulingService {
      throw new BadRequestException('Export marshalling document applies only to EXPORT schedules');
    }

-    const html = this.buildExportLoadListHtml(schedule);
+    const html = this.buildExportLoadListHtml(schedule, {
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
+    });
    // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
    const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Export marshalling / load list');
    const reference = schedule.trainNumber ?? schedule.id;
@@ -3117,6 +3122,7 @@ export class TrainSchedulingService {
      positionLabel,
      wagons,
      unassignedBookings,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
    });
    // Styled table-aware fallback (marshalling grid) — see importLoadListDocument.
    const buffer = await this.pdfDocuments.renderTabularDocument(html, 'Intercity marshalling / load list');
@@ -3160,6 +3166,7 @@ export class TrainSchedulingService {
      positionLabel?: string;
      wagons?: TrainSetWagon[];
      unassignedBookings?: Booking[];
+      logoImageUrl?: string | null;
    },
  ): string {
    const esc = (value: unknown) =>
@@ -3278,6 +3285,7 @@ export class TrainSchedulingService {
    .tile { border: 1px solid #cbd5e1; padding: 8px; min-height: 50px; }
    .tile span { display: block; color: #64748b; font-size: 9px; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 4px; }
    .tile strong { font-size: 11px; }
+    ${logoImageCss()}
    table { width: 100%; border-collapse: collapse; }
    th { background: #f8fafc; color: #475569; text-align: left; }
    th, td { border: 1px solid #cbd5e1; padding: 5px 6px; font-size: 9.5px; vertical-align: top; }
@@ -3292,6 +3300,7 @@ export class TrainSchedulingService {
 <body>
  <div class="top">
    <div>
+      ${logoMarkup(opts?.logoImageUrl)}
      <div class="brand">Ethio-Djibouti Railway S.C.</div>
      <h1>${esc(opts?.title ?? 'Export Marshalling Document / Load List')}</h1>
    </div>
@@ -3471,7 +3480,10 @@ export class TrainSchedulingService {
    }
  }

-  private buildImportLoadListHtml(loadList: Awaited<ReturnType<TrainSchedulingService['generateImportLoadList']>>): string {
+  private buildImportLoadListHtml(
+    loadList: Awaited<ReturnType<TrainSchedulingService['generateImportLoadList']>>,
+    logoImageUrl?: string | null,
+  ): string {
    const esc = (value: unknown) =>
      String(value ?? '-')
        .replace(/&/g, '&amp;')
@@ -3562,6 +3574,7 @@ export class TrainSchedulingService {
    .tile { border: 1px solid #cbd5e1; padding: 10px; min-height: 58px; }
    .tile span { display: block; color: #64748b; font-size: 10px; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 5px; }
    .tile strong { font-size: 13px; }
+    ${logoImageCss()}
    .status { display: grid; grid-template-columns: repeat(6, 1fr); gap: 8px; margin-top: 14px; }
    .step { border: 1px solid #cbd5e1; padding: 8px; font-size: 10px; text-align: center; min-height: 48px; }
    .done { background: #ecfdf5; border-color: #22c55e; color: #14532d; font-weight: 700; }
@@ -3583,6 +3596,7 @@ export class TrainSchedulingService {
  <div class="doc">
    <div class="top">
      <div>
+        ${logoMarkup(logoImageUrl)}
        <div class="brand">Ethio-Djibouti Railway S.C.</div>
        <h1>Import Load List /<br />Marshalling Document</h1>
        <div class="subtitle">Djibouti-side gatepass, loading, and departure manifest</div>
--- a/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
+++ b/apps/edr-freight-api/src/modules/warehouses/warehouse-inventory.service.ts
@@ -38,6 +38,8 @@ import {
 } from '../notifications/resolve-company-phone.util';
 import { SignaturesService } from '../signatures/signatures.service';
 import { StampSettingsService } from '../stamp-settings/stamp-settings.service';
+import { LogoSettingsService } from '../logo-settings/logo-settings.service';
+import { logoImageCss, logoMarkup } from '../billing/documents/logo-markup.util';
 import { sealClass, sealImageCss, sealMarkup } from '../billing/documents/seal-markup.util';
 import { BulkInspectDto } from './dto/bulk-inspect.dto';
 import { BulkReceiveDto, TruckEntranceDto } from './dto/bulk-receive.dto';
@@ -420,6 +422,7 @@ export class WarehouseInventoryService {
    private readonly inbox: NotificationInboxService,
    private readonly events: EventEmitter2,
    private readonly stampSettings: StampSettingsService,
+    private readonly logoSettings: LogoSettingsService,
  ) {}

  /**
@@ -3751,6 +3754,7 @@ export class WarehouseInventoryService {
      reference,
      issuedAt,
      stampImageUrl: await this.stampSettings.getStampImageUrl(),
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
      bookingReference,
      bookingStatus: row?.bookingStatus ?? null,
      customerName: row?.customerName ?? null,
@@ -4222,6 +4226,7 @@ export class WarehouseInventoryService {

    const html = this.buildGrnDocumentHtml({
      grnNumber: row.grnNumber,
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
      receivedAt: row.receivedAt ? new Date(row.receivedAt) : new Date(),
      bookingReference: row.bookingReference ?? row.bookingId ?? 'N/A',
      bookingStatus: row.bookingStatus ?? null,
@@ -4806,6 +4811,7 @@ export class WarehouseInventoryService {
      reference,
      handedOverAt,
      stampImageUrl: await this.stampSettings.getStampImageUrl(),
+      logoImageUrl: await this.logoSettings.getLogoImageUrl(),
      bookingReference,
      bookingStatus: row.bookingStatus ?? null,
      customerName: row.customerName ?? null,
@@ -5487,6 +5493,8 @@ export class WarehouseInventoryService {
    zone: string | null;
    inventoryStatus: string | null;
    receiveSummary: string | null;
+    /** The one global company logo; null renders the plain text brand. */
+    logoImageUrl?: string | null;
  }): string {
    const esc = (value: unknown) =>
      String(value ?? '-')
@@ -5543,6 +5551,7 @@ export class WarehouseInventoryService {
    .ref { text-align: right; font-size: 11px; color: #334155; padding-top: 8px; }
    .ref strong { display: block; color: #061323; font-size: 18px; margin: 5px 0 8px; letter-spacing: .02em; }
    .rule { height: 3px; background: #0f766e; margin: 16px 0 22px; }
+    ${logoImageCss()}
    .notice { width: 76%; margin: 0 0 18px; padding: 13px 18px; background: #f0fdfa; border: 1px solid #5eead4; border-left: 5px solid #0f766e; font-size: 13px; line-height: 1.45; }
    .section-title { margin: 18px 0 8px; font-size: 13px; font-weight: 800; color: #0f766e; text-transform: uppercase; letter-spacing: .12em; }
    table { width: 100%; border-collapse: collapse; }
@@ -5556,6 +5565,7 @@ export class WarehouseInventoryService {
 <body>
  <div class="top">
    <div>
+      ${logoMarkup(data.logoImageUrl)}
      <div class="brand">Ethio-Djibouti Railway S.C.</div>
      <h1>Goods Received Note</h1>
      <div class="subtitle">Warehouse receiving confirmation</div>
@@ -5613,6 +5623,8 @@ export class WarehouseInventoryService {
    truckWeightTons?: number | null;
    /** The one global company stamp; null falls back to the drawn text seal. */
    stampImageUrl?: string | null;
+    /** The one global company logo; null renders the plain text brand. */
+    logoImageUrl?: string | null;
  }): string {
    const esc = (value: unknown) =>
      String(value ?? '-')
@@ -5700,12 +5712,14 @@ export class WarehouseInventoryService {
    .seal::before { content: ""; position: absolute; width: 78px; height: 78px; border: 1px solid #17633a; border-radius: 999px; }
    .seal span { position: relative; }
    ${sealImageCss()}
+    ${logoImageCss()}
  </style>
 </head>
 <body>
  <div class="doc">
    <div class="top">
      <div>
+        ${logoMarkup(data.logoImageUrl)}
        <div class="brand">Ethio-Djibouti Railway S.C.</div>
        <h1>Warehouse Release / Exit Paper</h1>
        <div class="subtitle">Official gate clearance and warehouse exit authorization</div>
@@ -5775,6 +5789,8 @@ export class WarehouseInventoryService {
    } | null;
    /** The one global company stamp; null falls back to the drawn text seal. */
    stampImageUrl?: string | null;
+    /** The one global company logo; null renders the plain text brand. */
+    logoImageUrl?: string | null;
  }): string {
    const esc = (value: unknown) =>
      String(value ?? '-')
@@ -5853,11 +5869,13 @@ export class WarehouseInventoryService {
    .seal::before { content: ""; position: absolute; width: 78px; height: 78px; border: 1px solid #17633a; border-radius: 999px; }
    .seal span { position: relative; }
    ${sealImageCss()}
+    ${logoImageCss()}
  </style>
 </head>
 <body>
  <div class="top">
    <div>
+      ${logoMarkup(data.logoImageUrl)}
      <div class="brand">Ethio-Djibouti Railway S.C.</div>
      <h1>Import Goods Handover Document</h1>
      <div class="subtitle">EDR to customer warehouse handover</div>
--- a/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
+++ b/apps/edr-freight-api/src/seed/freight-permissions.registry.ts
@@ -1211,6 +1211,16 @@ export const CONFIG_SETTINGS_PERMISSIONS: FreightPermissionSeed[] = [
    "edr_freight_app:settings:stamp:manage",
    "Manage the company stamp",
  ),
+  perm(
+    "b4b00004-0001-4000-8000-000000000001",
+    "edr_freight_app:settings:logo:view",
+    "View the company logo",
+  ),
+  perm(
+    "b4b00004-0001-4000-8000-000000000002",
+    "edr_freight_app:settings:logo:manage",
+    "Manage the company logo",
+  ),
  // The per-officer approval teeter (ማህተም) — an individual's own stamp +
  // signature, not the company seal. It used to ride on settings:stamp:*, which
  // now gates the ONE company stamp; this key was split out when the two were
@@ -1935,6 +1945,12 @@ export const FREIGHT_PERMS = {
      view: "edr_freight_app:settings:stamp:view",
      manage: "edr_freight_app:settings:stamp:manage",
    },
+    // The ONE company logo, applied to every generated document (invoices,
+    // receipts, contracts, warehouse papers, train-scheduling manifests).
+    logo: {
+      view: "edr_freight_app:settings:logo:view",
+      manage: "edr_freight_app:settings:logo:manage",
+    },
    // The per-officer approval teeter (ማህተም) + signature — genuinely per-person,
    // and NOT the company seal above. Retired: `invoiceStamp`, which used to
    // gate the company stamp before the two were untangled.
--- a/apps/edr-freight-web/backoffice/src/App.tsx
+++ b/apps/edr-freight-web/backoffice/src/App.tsx
@@ -52,6 +52,7 @@ import NoAccessPage from "./pages/NoAccessPage";
 import FileUploadSettingsPage from "./pages/documents/FileUploadSettingsPage";
 import DropdownSettingsPage from "./pages/dropdown_settings/DropdownSettingsPage";
 import CompanyStampSettingsPage from "./pages/settings/CompanyStampSettingsPage";
+import LogoSettingsPage from "./pages/settings/LogoSettingsPage";
 import ContractTemplatesPage from "./pages/contract_templates/ContractTemplatesPage";
 import PortalContentPage from "./pages/portal_content/PortalContentPage";
 import ContractTemplateEditorPage from "./pages/contract_templates/ContractTemplateEditorPage";
@@ -807,6 +808,15 @@ const App = () => {
          path="invoice-stamp-settings"
          element={<Navigate to="/dashboard/stamp-settings" replace />}
        />
+        {/* The ONE company logo, shown in the header of every generated document. */}
+        <Route
+          path="logo-settings"
+          element={
+            <RequirePermission permission={FREIGHT_PERMS.settings.logo.view}>
+              <LogoSettingsPage />
+            </RequirePermission>
+          }
+        />
        <Route
          path="contract-templates"
          element={
--- a/apps/edr-freight-web/backoffice/src/components/contracts/LogoUpload.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/contracts/LogoUpload.tsx
@@ -0,0 +1,172 @@
+import { useRef, useState } from "react";
+import { Box, Button, Group, Image, Paper, Stack, Text } from "@mantine/core";
+import { ImageIcon, RefreshCw, X } from "lucide-react";
+
+const MAX_LOGO_MB = 10;
+
+export interface LogoUploadProps {
+  /** Logo image as a data URL, or null when none is attached yet. */
+  value: string | null;
+  onChange: (dataUrl: string | null) => void;
+  label?: string;
+  description?: string;
+}
+
+/**
+ * Company logo picker — reads the picked image straight into a data URL,
+ * same transport as {@link StampUpload}. Kept as its own component (not a
+ * generalized image-upload) matching how stamp/teeter are already separate
+ * files here despite the near-identical shape.
+ */
+export function LogoUpload({
+  value,
+  onChange,
+  label = "Company logo",
+  description = "Attach the official company logo.",
+}: LogoUploadProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const [dragging, setDragging] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fileName, setFileName] = useState<string | null>(null);
+
+  const readFile = (file: File | undefined | null) => {
+    if (!file) return;
+    if (!file.type.startsWith("image/")) {
+      setError("The logo must be an image file (PNG or JPG).");
+      return;
+    }
+    if (file.size > MAX_LOGO_MB * 1024 * 1024) {
+      setError(`The logo image must be under ${MAX_LOGO_MB} MB.`);
+      return;
+    }
+    const reader = new FileReader();
+    reader.onload = () => {
+      setError(null);
+      setFileName(file.name);
+      onChange(typeof reader.result === "string" ? reader.result : null);
+    };
+    reader.onerror = () => setError("Could not read that file. Try another.");
+    reader.readAsDataURL(file);
+  };
+
+  const openPicker = () => inputRef.current?.click();
+
+  const clear = () => {
+    setFileName(null);
+    setError(null);
+    onChange(null);
+    if (inputRef.current) inputRef.current.value = "";
+  };
+
+  return (
+    <Stack gap={6}>
+      <Text size="sm" fw={500}>
+        {label}
+      </Text>
+
+      <input
+        ref={inputRef}
+        type="file"
+        accept="image/png,image/jpeg,image/webp"
+        hidden
+        onChange={(e) => readFile(e.currentTarget.files?.[0])}
+      />
+
+      {value ? (
+        <Paper withBorder radius="md" p="sm">
+          <Group gap="md" wrap="nowrap" align="center">
+            <Box
+              style={{
+                background:
+                  "repeating-conic-gradient(var(--mantine-color-gray-1) 0% 25%, transparent 0% 50%) 50% / 14px 14px",
+                borderRadius: 8,
+                flexShrink: 0,
+                padding: 6,
+              }}
+            >
+              <Image
+                src={value}
+                alt="Company logo"
+                fit="contain"
+                h={92}
+                w={92}
+              />
+            </Box>
+            <Stack gap={4} style={{ flex: 1, minWidth: 0 }}>
+              <Text size="sm" fw={500} truncate>
+                {fileName ?? "Logo attached"}
+              </Text>
+              <Text size="xs" c="dimmed">
+                Shown in the header of every generated document.
+              </Text>
+              <Group gap="xs" mt={2}>
+                <Button
+                  size="compact-xs"
+                  variant="light"
+                  color="edr-green"
+                  leftSection={<RefreshCw size={13} />}
+                  onClick={openPicker}
+                >
+                  Replace
+                </Button>
+                <Button
+                  size="compact-xs"
+                  variant="subtle"
+                  color="red"
+                  leftSection={<X size={13} />}
+                  onClick={clear}
+                >
+                  Remove
+                </Button>
+              </Group>
+            </Stack>
+          </Group>
+        </Paper>
+      ) : (
+        <Paper
+          withBorder
+          radius="md"
+          p="lg"
+          onClick={openPicker}
+          onDragOver={(e) => {
+            e.preventDefault();
+            setDragging(true);
+          }}
+          onDragLeave={() => setDragging(false)}
+          onDrop={(e) => {
+            e.preventDefault();
+            setDragging(false);
+            readFile(e.dataTransfer.files?.[0]);
+          }}
+          style={{
+            borderColor: dragging
+              ? "var(--mantine-color-edr-green-6)"
+              : undefined,
+            borderStyle: "dashed",
+            backgroundColor: dragging
+              ? "var(--mantine-color-edr-green-0)"
+              : undefined,
+            cursor: "pointer",
+          }}
+        >
+          <Stack gap={6} align="center">
+            <ImageIcon size={26} color="var(--mantine-color-edr-green-6)" />
+            <Text size="sm" fw={500}>
+              Upload company logo
+            </Text>
+            <Text size="xs" c="dimmed" ta="center">
+              {description} Drop an image here or click to browse — PNG or JPG,
+              up to {MAX_LOGO_MB} MB.
+            </Text>
+          </Stack>
+        </Paper>
+      )}
+
+      {error && (
+        <Text size="xs" c="red.7">
+          {error}
+        </Text>
+      )}
+    </Stack>
+  );
+}
--- a/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
+++ b/apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
@@ -9,6 +9,7 @@ import {
  FileText,
  Hammer,
  History,
+  Image as ImageIcon,
  Landmark,
  LayoutDashboard,
  LayoutGrid,
@@ -495,6 +496,12 @@ export const buildSidebarSections = (demoItems: SidebarItem[]): SidebarSection[]
        icon: <Stamp />,
        permission: FREIGHT_PERMS.settings.stamp.view,
      },
+      {
+        label: "Company logo",
+        href: "/dashboard/logo-settings",
+        icon: <ImageIcon />,
+        permission: FREIGHT_PERMS.settings.logo.view,
+      },
      {
        label: "Contract templates",
        href: "/dashboard/contract-templates",
--- a/apps/edr-freight-web/backoffice/src/hooks/useLogoSettings.ts
+++ b/apps/edr-freight-web/backoffice/src/hooks/useLogoSettings.ts
@@ -0,0 +1,45 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import { logoSettingsService } from "@/services/logoSettings.service";
+import { useErrorHandler } from "@/shared/hooks/useErrorHandler";
+
+const QUERY_KEY = ["logoSettings"];
+
+export const useLogoSettingsQuery = () =>
+  useQuery({
+    queryKey: QUERY_KEY,
+    queryFn: () => logoSettingsService.get(),
+  });
+
+export const useSetLogo = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: (logoImageBase64: string) =>
+      logoSettingsService.set(logoImageBase64),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+      toast.success(t("logoSettings.updated", "Company logo updated"));
+    },
+    onError: handleError,
+  });
+};
+
+export const useClearLogo = () => {
+  const queryClient = useQueryClient();
+  const { t } = useTranslation();
+  const { handleError } = useErrorHandler(t);
+
+  return useMutation({
+    mutationFn: () => logoSettingsService.clear(),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: QUERY_KEY });
+      toast.success(t("logoSettings.cleared", "Company logo removed"));
+    },
+    onError: handleError,
+  });
+};
--- a/apps/edr-freight-web/backoffice/src/lib/permissions.ts
+++ b/apps/edr-freight-web/backoffice/src/lib/permissions.ts
@@ -334,6 +334,12 @@ export const FREIGHT_PERMS = {
      view: "edr_freight_app:settings:stamp:view",
      manage: "edr_freight_app:settings:stamp:manage",
    },
+    // The ONE company logo, applied to every generated document (invoices,
+    // receipts, contracts, warehouse papers, train-scheduling manifests).
+    logo: {
+      view: "edr_freight_app:settings:logo:view",
+      manage: "edr_freight_app:settings:logo:manage",
+    },
    // The per-officer approval teeter (ማህተም) + signature — genuinely per-person,
    // and NOT the company seal above. Retired: `invoiceStamp`, which used to
    // gate the company stamp before the two were untangled.
--- a/apps/edr-freight-web/backoffice/src/pages/settings/LogoSettingsPage.tsx
+++ b/apps/edr-freight-web/backoffice/src/pages/settings/LogoSettingsPage.tsx
@@ -0,0 +1,88 @@
+import { useEffect, useState } from "react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/shared/common/ui/card";
+import { Button } from "@/shared/common/ui/button";
+import { Save, Trash2 } from "lucide-react";
+
+import { LogoUpload } from "@/components/contracts/LogoUpload";
+import {
+  useClearLogo,
+  useSetLogo,
+  useLogoSettingsQuery,
+} from "@/hooks/useLogoSettings";
+
+/**
+ * The ONE company logo, read by every document path server-side via
+ * LogoSettingsService: invoices and receipts, contract cover pages, warehouse
+ * GRN/release/handover papers, train-scheduling manifests, and the payment
+ * receipt. Single global image — no per-document choice.
+ */
+export default function LogoSettingsPage() {
+  const { data, isLoading } = useLogoSettingsQuery();
+  const setLogo = useSetLogo();
+  const clearLogo = useClearLogo();
+  const [draft, setDraft] = useState<string | null>(null);
+
+  useEffect(() => {
+    setDraft(null);
+  }, [data?.logoImageUrl]);
+
+  const value = draft !== null ? draft : (data?.logoImageUrl ?? null);
+  const dirty = draft !== null && draft !== data?.logoImageUrl;
+
+  const handleSave = async () => {
+    if (!draft) return;
+    await setLogo.mutateAsync(draft);
+  };
+
+  const handleClear = async () => {
+    if (!data?.logoImageUrl) return;
+    await clearLogo.mutateAsync();
+  };
+
+  return (
+    <div className="p-4 w-full max-w-screen-sm mx-auto">
+      <Card className="shadow-lg border-gray-200 dark:border-gray-700">
+        <CardHeader>
+          <CardTitle>Company logo</CardTitle>
+          <CardDescription>
+            The single EDR logo, applied to every generated document —
+            invoices and receipts, contracts, warehouse papers, train-scheduling
+            manifests, and payment receipts. Replacing it here changes it
+            everywhere at once.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <LogoUpload
+            value={isLoading ? null : value}
+            onChange={setDraft}
+            label="Company logo"
+            description="Shown in the header of every generated document."
+          />
+
+          <div className="flex items-center gap-2">
+            <Button onClick={handleSave} disabled={!dirty || setLogo.isPending}>
+              <Save className="mr-2 h-4 w-4" />
+              Save
+            </Button>
+            {data?.logoImageUrl && !dirty && (
+              <Button
+                variant="outline"
+                onClick={handleClear}
+                disabled={clearLogo.isPending}
+              >
+                <Trash2 className="mr-2 h-4 w-4" />
+                Remove
+              </Button>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
--- a/apps/edr-freight-web/backoffice/src/services/logoSettings.service.ts
+++ b/apps/edr-freight-web/backoffice/src/services/logoSettings.service.ts
@@ -0,0 +1,31 @@
+import { api as client } from "../auth/http";
+import { unwrap } from "@/utils/endpoint";
+import type { ApiResponse } from "@/types/apiResponse";
+
+const BASE = "/logo-settings";
+
+/** Company logo used on every generated document. */
+export interface LogoSettings {
+  logoImageUrl: string | null;
+  updatedById: string | null;
+  updatedAt: string | null;
+}
+
+export const logoSettingsService = {
+  get: async (): Promise<LogoSettings> => {
+    const response = await client.get<ApiResponse<LogoSettings>>(BASE);
+    return unwrap(response.data);
+  },
+
+  set: async (logoImageBase64: string): Promise<LogoSettings> => {
+    const response = await client.put<ApiResponse<LogoSettings>>(BASE, {
+      logoImageBase64,
+    });
+    return unwrap(response.data);
+  },
+
+  clear: async (): Promise<LogoSettings> => {
+    const response = await client.delete<ApiResponse<LogoSettings>>(BASE);
+    return unwrap(response.data);
+  },
+};