OFM - Org and Facility Management

OFM is the tenant backbone of the stack. It defines the organization, who belongs to it, what facilities it operates, and which sales channels it sells through. If you need to answer, "Which organization is this and who can act for it?", OFM is the source of truth.

OFM is both structural and governance-oriented. It stores the organization record, tracks owners and members, and enforces status rules that can block or allow activity across the rest of the stack.

Service scope and boundaries

OFM owns organizational structure and governance. It does not authenticate users (UAS/USM) and it does not model products (PVM). Its job is to define the tenant, the people who belong to it, the facilities it operates, and the sales channels it uses.

Implemented feature breakdown (what exists today)

• Org lifecycle: unverified, verified, parked, suspended, frozen, doomed.
• Owner and member model: owners are members with elevated authority; members have roles and grants.
• Member onboarding: owner-managed invite and accept flows within an org.
• Org-level onboarding: operator-controlled for closed onboarding posture.
• Facilities: physical, legal, and logical facilities.
• Zones: subdivisions of logical facilities with strict lifecycle rules.
• Teams: org-wide or logical-scoped teams for coordination.
• Cost centres: org-level cost centre records.
• Resolvers: org and facility resolution helpers (orgcode and related lookups).
• Sales channels: channel declarations with market/locale context and configuration pointers.
• Access control: role- and membership-based authorization plus anti-enumeration behavior.

How the features are implemented (behavioral breakdown)

Org lifecycle and write gating

• Orgs begin unverified.
• Operators can verify, suspend, freeze, or doom an org.
• Owners can park and unpark an org with a cooldown.
• When an org is not verified (unverified/parked/suspended), tenant writes across services are blocked.
• Frozen blocks tenant reads and writes across services (operator-only; used for offboarding). Frozen can only transition to doomed.
• Doomed is terminal.

Owners and members

• Owners are members with elevated authority.
• Members have roles and grants that control what they can do.
• A caller who is not associated with an org is treated as if the org does not exist.

Member onboarding inside an org

1. An owner issues a member invite for a specific user identity.
2. The invited user accepts the invite using their own session.
3. Roles and grants are set based on responsibilities.

Facility spine

• Physical facilities represent real-world locations.
• Legal facilities represent registered legal entities.
• Logical facilities represent operational groupings such as warehouses or regions.
• Logical facilities can contain zones for internal operational structure.

Zones

• Every logical facility has a ROOT zone.
• Zones follow a strict lifecycle; doomed is terminal.
• Logical facility state can block zone writes to prevent invalid structures.

Teams

• Teams can be org-wide or logical-scoped.
• Teams are grouping and coordination tools, not an authorization source of truth.

Sales channels

• A channel declaration defines the selling surface and its market/locale context.
• Configuration content is stored via a pointer flow so that channel records remain lean.
• Some channel actions are delegated for facility-scoped members, while activation and terminal status changes remain owner-only.

Example use cases (extensive)

New merchant onboarding: An organization is created, owners are assigned, and the org is verified by an operator. Facilities are defined (physical, legal, logical), and zones are added. Only after verification can downstream writes occur.

Member onboarding: An owner invites a new team member, who accepts the invite using their own session. Roles and grants are assigned based on responsibilities (for example, product admins vs viewers). The member can now act in downstream services within their granted scope.

Facility expansion: A business opens a new warehouse. A new physical facility is created, a matching legal facility is added, and a logical facility is defined to represent operations. Zones are created for inbound, storage, and outbound operations.

Channel activation: A new marketplace channel is declared with its market and locale list. Configuration is uploaded through a pointer flow and activated. PMC can now publish products into that channel.

Compliance pause: An org is suspended by an operator. All tenant writes across services are blocked until the org is verified again. Reads can continue so the business can inspect state without making changes.

Delegated operations: A facility-scoped member is allowed to manage zones or draft sales-channel configuration for their logical facility without granting full org-owner privileges.

Example scenarios and acceptance criteria

Scenario 1: Org verification gates writes

• An org is created and remains unverified.
• A downstream write is attempted (for example, PVM create).
• Acceptance: the write is blocked until an operator verifies the org; reads remain available.

Scenario 2: Member invite and scoped access

• An owner invites a member and assigns a limited role set.
• The member accepts and attempts both allowed and disallowed actions.
• Acceptance: allowed actions succeed; disallowed actions are rejected with clear audit trails.

Scenario 3: Sales channel configuration pointer flow

• A channel declaration is created with market and locale context.
• Config is uploaded via a pointer flow and activated by an owner.
• Acceptance: channel records remain lean; config references are immutable per version and auditable.

Scenario 4: Facility-scoped delegation for zones

• A member is granted access to a specific logical facility.
• The member creates zones within that facility.
• Acceptance: zone writes are allowed only within the granted facility; other facilities remain inaccessible.

Constraints and invariants

• OFM is intentionally strict about access. Owners have broad authority; members must have explicit roles and grants.
• Anti-enumeration: if a caller is not associated with an org, the org is treated as not found.
• Org status gating blocks tenant writes across services when an org is not verified.
• Doomed is terminal for orgs and facility-related records.
• Teams do not grant permissions; they are organizational groupings only.

How OFM fits with other services

USM provides session authentication. OFM resolves those sessions into org roles and membership, which downstream services use for authorization. PVM, MRS, and PMC all rely on OFM to decide whether a caller is allowed to act within a given organization. PMC also relies on OFM sales channel declarations to define product identity per channel.

Implemented vs planned

Implemented: org lifecycle and write gating, owners and members, facilities and zones, teams, cost centres, resolvers, and sales channel declarations with configuration pointers.

Sales channel identity fields (confirmed baseline):

• channel_code: registry-backed connector family (lowercase snake_case).
• market_code: ISO‑3166 country code (strict allowlist).
• locale_codes: non-empty array of canonical BCP‑47 locales.
• default_locale_code: required when multiple locales; must be in locale_codes.
• logical_guid: facility binding (must exist and not be doomed).
• external_ids[]: optional integration identifiers; duplicates allowed for migration, but only one active binding resolves at a time.
• caption: human label for instance identity (display-only).
• config pointer metadata: S3 bucket/key/version/etag/size (pointer only; never inline).

Activation validation (confirmed baseline):

• expected_revision required; status must be draft.
• channel_code in registry; market_code allowlisted; locales canonicalized.
• If a locale has a region subtag (e.g., en-US), it must match market_code.
• logical_guid must belong to the org and be active.
• Config pointer metadata required and must reference a versioned object.

Governance baseline:

• Owners can activate/inactivate/doom.
• Delegated members can create/edit drafts; activation remains owner-only.

For exact request and response shapes, see the OFM contract pages at https://doc.g3nretailstack.com/ofm/.