Overview

Fact: an address row now exists for a franchise unit in common.addresses. The payload is the same address block that travels inside Franchise CreatedFranchise CreatedEvent•v1.2.0A franchise unit was created in CNA Nexus by activating an opening contract. Full snapshot of the unit; cna-one mirrors ...Ownercna-platformSchemaMapView docs and Franchise UpdatedFranchise UpdatedEvent•v1.2.0A franchise unit changed in CNA Nexus - edited in one of the franchise screens, re-activated from a contract, or amended...Ownercna-platformSchemaMapView docs (FranchiseAddressData), plus franchiseId so the consumer can find the unit without the full snapshot. See Franchise AddressFranchise AddressEntity•v1.0.0The address of a franchise unit - street, number, complement, neighborhood, postal code, IBGE city or foreign city and s...Ownercna-platformView docs.

When it is published. CNA NexusCNA NexusService•v1.0.0Franchise network back-office (franchises, economic groups, partners, contracts and amendments, document storage, AI doc...PublishesInviteUser, ContractActivationRequested +13SubscribesContractActivationRequested, AmendmentApplyRequested +4Ownercna-platformMapRepoView docs, always through manager.afterCommit(), whenever an address row is inserted for a franchise: the createAddress GraphQL mutation (createFranchiseAddress) and createFranchiseForOpening, when the unit is created from an opening ContractContractEntity•v1.0.0A franchise contract in CNA Nexus - opening, renewal or resale - uploaded as a document, analysed by AI, reviewed by a p...Ownercna-platformView docs. In the second case the same commit also emits FranchiseCreated, which carries the same address in payload.address; the consumer’s upsert is idempotent, so the overlap is harmless. Every later change goes out as Franchise Address UpdatedFranchise Address UpdatedEvent•v1.0.0The address of a franchise unit changed in CNA Nexus. The address block of the franchise snapshot plus the franchise id....Ownercna-platformSchemaMapView docs.

What the consumer does. CNA OneCNA OneService•v1.0.0Franchise operating system (franchises and employees, pricing, products and learning books, school operations). Publishe...PublishesGrantApplicationAccess, EmployeeCreated +6SubscribesInviteUser, FranchiseCreated +9Ownercna-platformMapRepoView docs (franchiseConsumer, group franchise-franchise-events, handler syncFranchiseAddress): loads the franchise by franchiseId and, when the unit is not mirrored yet, logs a warning and drops the message — a unit is created without a CNPJ and cna-one mirrors it only once the CNPJ arrives, so the address of an opening, and every address edit before the CNPJ, reaches cna-one ahead of the unit; the Franchise UpdatedFranchise UpdatedEvent•v1.2.0A franchise unit changed in CNA Nexus - edited in one of the franchise screens, re-activated from a contract, or amended...Ownercna-platformSchemaMapView docs that brings the CNPJ brings the address too. Otherwise it requires street, number, neighborhood, postalCode and an IBGE cityId known to cna-one, turns latitude and longitude into one PostGIS point when both are present and on the globe — a pair with one side missing, unreadable or off the globe is logged and the address is stored without a point — and upserts the unit’s row in its own common.addresses. cityName, state, countryId, foreignCity and foreignState are ignored, so an address outside Brazil is not mirrored. Failures are logged and reported to Sentry, never rethrown.

Kafka

Payload schema

FranchiseAddressData from FranchiseCreated plus franchiseId. countryId is the only required address field; a Brazilian address fills cityId, cityName and state, an address outside Brazil fills foreignCity and foreignState instead.

Source of truth

import { FranchiseAddressData } from 'events/nexus/franchise/FranchiseCreated';

export type FranchiseAddressPayload = FranchiseAddressData & {
  franchiseId: string;
};

export class FranchiseAddressCreated extends Event<FranchiseAddressPayload> {
  static readonly owner = 'NEXUS';
  static readonly aggregateRoot = 'Franchise';
  static readonly routingKey = 'franchiseId';
  static readonly version = '1.0.0';
}

Known drift

Observed 2026-09-23.

• cna-nexus, the canonical repository, has no FranchiseAddressCreated class and emits nothing from the address write paths yet. The class above is the target; this page is written against the pending cna-nexus pull request and the link goes here when it opens.
• cna-one api/app/events/nexus/franchise/FranchiseAddressCreated.ts exists only on branch jl/feature/CWH-48874-consume-franchise-address-events (not merged into staging) and matches the class above: same fields, key and version.