Business Affiliate Module

Status: Live. This module is built and running. The engineering reference for what ships today is kept at Business Affiliate (Q2 2026).

Purpose

A Business Affiliate is an external party a tenant does business with — a vendor, a customer, a carrier, an operator, and so on. Each affiliate carries the descriptive details you would expect: a name, contacts, and addresses.

A supplier is not a separate thing. It is a business affiliate seen through its vendor role. This is the single most important idea in the module: rather than keeping a “supplier” list apart from a “customer” list apart from a “carrier” list, the system keeps one list of affiliates, and each affiliate carries one or more roles that say what it acts as.

Main entities

An affiliate owns a set of roles, each typed by what the affiliate does in that capacity. Other modules that need a supplier point at the affiliate’s vendor role through a lightweight supplier reference.

• Business Affiliate — the external party itself, with its name, contacts, and addresses.
• Business Role — a capacity the affiliate acts in: Vendor, Customer, Carrier, Operator, or Other. One affiliate can bear several roles at once (a company can be both a vendor and a customer).
• Supplier reference — a lightweight handle other modules keep when they need to name a supplier. It carries the vendor’s name plus a soft link to the vendor role. It is not a hard database link: it can be a name only (an informal supplier that was never fully entered), and it always resolves through this module rather than by a direct join.

Operations

Action	What it does	When it is allowed
Create / update / delete	Standard management of an affiliate and its roles, with full history kept.	Any time.
Query / filter by role	List affiliates, optionally filtered to a role such as Vendor.	Any time.
Resolve or create a supplier	When another module names a supplier, the system finds the matching vendor — or creates the affiliate and its vendor role on the fly.	On demand from a consuming module.

Guarantees

• A role belongs to exactly one affiliate. Roles are never shared between affiliates.
• An affiliate can act in several roles at once — vendor and customer, for example — without duplicating the affiliate.
• The same supplier is reused, not duplicated. Naming a supplier that already exists links to the existing vendor role rather than creating a second one.
• Supplier references never dangle silently. When a vendor is renamed, the new name flows out to everything that references it; when a vendor is removed, the references that pointed at it are marked stale (kept, not deleted) so nothing silently breaks and no in-flight work loses its supplier.

How it relates to its neighbors

• Item — an item’s supply sources name their supplier through a supplier reference that resolves to a vendor role here.
• Orders — an order commits to a supplier by referencing a vendor role, frozen into the order at submission.