Fusion Architecture Guide

Document Info

Executive Summary

Fusion is a unified platform that replaces the fragmented integrations across Elm Street Technology's product ecosystem (IDX Broker, Outbound Engine, VoicePad, AIVA, CRM) with a clean, modular architecture.

At its core is the Party Model — an industry-standard pattern (Salesforce, SAP, Oracle) that represents any participant in the system — person, organization, or external system — in a consistent, extensible way. Around this identity core, Fusion layers Billing, Subscriptions, and Product Catalog modules that integrate with Zuora as the billing provider.

This architecture solves key challenges around:

• Connecting Auth0 SSO identities to business entities
• Representing MLS listing/agent/office relationships
• Supporting multiple agent roles (listing agent, buyer agent, co-agent, etc.)
• Centralizing billing and subscription management through Zuora
• Managing product catalogs with rate plan groups and dependencies
• Supporting developer partner billing hierarchies (direct, partner-controlled, aggregate)
• Building a foundation for CRM functionality
• Maintaining a single source of truth for identity, billing, and subscription data

The Problem Fusion Solves

Fragmented Identity

Fragmented Products

Fragmented Billing

Result: We can't answer simple questions like:

• "Show me all accounts this person has access to"
• "Who are the agents under this developer partner?"
• "What role does this person play on this listing?"
• "What subscriptions does this customer have and what do they cost?"
• "Which rate plans can be added given the current subscription?"

Example Scenario

Natalie More is:

1. An Auth0 user who logs into Fusion
2. An individual agent with her own IDX Broker account (#60869)
3. A member of SWFLGC MLS with agent ID 26563084
4. The listing agent on property 2025017196
5. Managed by developer partner "BulletProof Real Estate Agent"
6. Billed via Zuora with a client_direct billing arrangement
7. Subscribed to IDX Broker Core (Monthly) with an MLS fee

Question: How do we connect all of these identities, products, and billing relationships?

System Architecture

Module Structure

Fusion uses a modular Laravel architecture with four bounded modules:

modules/
├── Identity/        Core identity: parties, users, products, customer provisioning
├── Billing/         Billing accounts, invoices, payments, payment methods
├── Subscriptions/   Subscriptions, rate plans, catalog, amendments
└── Zuora/           Zuora API adapter implementing Billing + Subscription contracts

Each module has its own models, actions, controllers, tests, events, and service provider. Modules communicate through contracts (interfaces), never through direct class references to another module's internals.

Architecture Layers

┌─────────────────────────────────────────────────────────────────────────────────┐
│  AUTHENTICATION LAYER                                                           │
│  Auth0 (External IdP)                                                           │
│  • Handles SSO, social login, MFA                                               │
│  • Owns: sub (subject identifier), email                                        │
└───────────────────────────────────────────────┬─────────────────────────────────┘
                                                │
                                                ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│  APPLICATION LAYER                                                              │
│  users table                                                                    │
│  • Links Auth0 to internal system                                               │
│  • Owns: auth0_sub, email                                                       │
│  • References: party_id → The person behind this login                          │
└───────────────────────────────────────────────┬─────────────────────────────────┘
                                                │
                                                ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│  PARTY LAYER (Identity Module)                                                  │
│  parties — The canonical identity AND customer account                          │
│  • type: person, organization, system                                           │
│  • Owns: first_name/last_name (persons) / display_name (orgs)                   │
│                                                                                 │
│  party_identifiers — External system IDs (MLS member IDs, idx_id)               │
│  party_groups / party_group_members — Flexible grouping with roles              │
│  party_roles — Role a party plays on business objects (listing_agent, etc.)      │
│  party_product — Links parties to products with roles (owner, agent, admin)      │
└───────────────────────┬───────────────────────┬─────────────────────────────────┘
                        │                       │
         ┌──────────────┘                       └──────────────┐
         ▼                                                     ▼
┌─────────────────────────────────┐     ┌──────────────────────────────────────────┐
│  PRODUCT LAYER (Identity)       │     │  BILLING LAYER (Billing Module)          │
│                                 │     │                                          │
│  products                       │     │  billing_providers (Zuora)               │
│  • IDX Broker, Outbound Engine  │     │  billing_accounts                        │
│  • VoicePad, AIVA, CRM         │     │  • Links Party to BillingProvider         │
│                                 │     │  • external_account_id (Zuora ID)        │
│  product_accounts               │     │  • billing_type: client_direct,          │
│  • Specific account instance    │     │    partner_controlled, aggregate         │
│  • product_account_id: 60869    │     │                                          │
│  • billing_account_id → billing │     │  invoices, payments, payment_methods     │
│                                 │     │  • Full billing lifecycle                │
└─────────────────────────────────┘     └──────────────────────────────────────────┘
         │                                                     │
         └──────────────────────┬──────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│  SUBSCRIPTION LAYER (Subscriptions Module)                                      │
│                                                                                 │
│  subscriptions — Synced from Zuora via SyncAccountSubscriptions                 │
│  subscription_items — Individual charges on a subscription                      │
│                                                                                 │
│  PRODUCT CATALOG:                                                               │
│  rate_plan_groups — Organize rate plans (selection_mode: one/many)               │
│  product_rate_plans — Catalog entries with group + dependency references         │
│  product_pricing — Charges/prices for each rate plan                            │
│  mls_fee_mappings — MLS-specific fee rate plans                                 │
│                                                                                 │
│  AMENDMENT SERVICE:                                                             │
│  SubscriptionAmendmentService — Single entry point for all plan changes         │
│  • Enforces exclusive groups, required groups, cascading dependencies            │
│  • Idempotent: duplicate adds and missing removes are safe no-ops               │
└─────────────────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│  PROVIDER LAYER (Zuora Module)                                                  │
│                                                                                 │
│  ZuoraAdapter — Implements BillingProviderContract + SubscriptionProviderContract│
│  • Account CRUD, invoices, payments, payment methods                            │
│  • Subscription CRUD, rate plan add/remove/swap                                 │
│  • Product catalog sync                                                         │
│  • Mappers convert Zuora responses to provider-agnostic data objects            │
└─────────────────────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│  BUSINESS OBJECTS LAYER (Future)                                                │
│  listings, transactions, leads, contacts                                        │
│  • Connected to parties via party_roles                                         │
│  • Routed via subscription data (Contact Service)                               │
└─────────────────────────────────────────────────────────────────────────────────┘

Entity Relationship Diagram

erDiagram
    Auth0 ||--o| User : authenticates
    User ||--o| Party : "is a"

    Party ||--o{ PartyIdentifier : has
    Party ||--o{ PartyGroupMember : "member of"
    Party ||--o{ PartyRole : plays
    Party ||--o{ PartyProduct : "has access to"
    Party ||--o{ BillingAccount : "billed via"

    PartyGroup ||--o{ PartyGroupMember : contains
    PartyGroup }o--o| Party : "created by"

    PartyType ||--o{ Party : classifies
    PartySubtype ||--o{ Party : classifies
    PartyType ||--o{ PartySubtype : contains

    RoleType ||--o{ PartyRole : defines

    PartyProduct }o--|| Product : "for"
    PartyProduct }o--o| ProductAccount : references

    Product ||--o{ ProductAccount : has
    Product ||--o{ RatePlanGroup : "catalog groups"
    ProductAccount }o--o| BillingAccount : "billed via"

    BillingAccount }o--|| BillingProvider : "at"
    BillingAccount ||--o{ Subscription : has
    BillingAccount ||--o{ Invoice : has
    BillingAccount ||--o{ PaymentMethod : has
    Invoice ||--o{ Payment : "paid by"

    Subscription ||--o{ SubscriptionItem : contains

    RatePlanGroup ||--o{ ProductRatePlan : contains
    RatePlanGroup }o--o| RatePlanGroup : "depends on"
    ProductRatePlan ||--o{ ProductPricing : "priced by"
    ProductRatePlan }o--o| ProductRatePlan : "requires"

    PartyRole }o--|| Listing : "on"

Identity Module

Party — "Who Is This?"

A Party is any entity that participates in business relationships. This is both the identity and the customer account in one model — no separate "Tenant" or "Account" model needed.

Every person, company, MLS, and system in Fusion is a Party.

Party Types

Party Structure

Party
├── first_name / last_name (for persons)
├── display_name (for organizations)
├── metadata (JSON — phones, emails, extra data)
├── PartyIdentifiers → External IDs (MLS agent #, idx_id)
├── PartyGroups → Group memberships (via PartyGroupMember)
├── PartyRoles → Roles on business objects (listings)
├── PartyProducts → Product access with roles
├── BillingAccounts → Billing relationships
└── User → Auth0 login (optional — not all parties log in)

PartyIdentifier — "What External IDs Do They Have?"

External identifiers from other systems that belong to a Party. Parties can have multiple IDs from multiple sources.

PartyGroup — "What Groups Are They In?"

A named group of Parties used to organize entities together. Members join groups via PartyGroupMember with a role and status.

Why groups? Groups replace individual party-to-party relationships with a single, flexible many-to-many pattern. Office affiliations, developer partner client lists, brokerage teams, and employment all use the same mechanism — a PartyGroup with members who have explicit roles. This avoids a proliferation of relationship types and makes it easy to query "who belongs to what" in one place.

Group Structure

PartyGroup
├── name → Human-readable group name
├── description → Optional description
├── created_by_party_id → Party that created the group
└── members → Parties in this group (via PartyGroupMember)

PartyGroupMember (Pivot)

Common Group Patterns

Developer Partner Managing Clients:

PartyGroup: "BulletProof Clients"
├── created_by: BulletProof Real Estate Agent
├── PartyGroupMember: BulletProof Real Estate Agent (role: admin)
├── PartyGroupMember: Natalie More (role: client)
└── PartyGroupMember: Bob Smith (role: client)

Office Affiliation (replaces affiliated_with relationship):

PartyGroup: "Realty One Group MVP Agents"
├── created_by: Realty One Group MVP
├── PartyGroupMember: Realty One Group MVP (role: owner)
├── PartyGroupMember: Bob Broker (role: team_lead)
├── PartyGroupMember: Natalie More (role: member)
└── PartyGroupMember: Alice Agent (role: member)

Internal Team (replaces employed_by relationship):

PartyGroup: "BulletProof Team"
├── created_by: BulletProof Real Estate Agent
├── PartyGroupMember: BulletProof Real Estate Agent (role: admin)
└── PartyGroupMember: Anthony Colletti (role: member)

PartyRole — "What Role Do They Play on Things?"

A role that a Party plays on a business object (listing, transaction, lead). Uses polymorphic relationships to connect parties to any subject type.

Listing "2025017196"
├── PartyRole: Natalie More (listing_agent, is_primary: true)
├── PartyRole: Bob Smith (co_listing_agent)
└── PartyRole: Realty One Group MVP (listing_office)

PartyProduct — "What Products Can They Access?"

Links a Party to a Product with a specific role and account instance. Multiple people can access the same product account with different permissions.

Individual Agent:

Party: Natalie More
└── PartyProduct (role: owner)
      ├── Product: IDX Broker
      └── ProductAccount: #60869

Brokerage Office:

Party: Bob Broker ──── PartyProduct (role: owner) ────┐
                                                      │
Party: Natalie More ── PartyProduct (role: agent) ────┼──▶ ProductAccount: #78901
                                                      │    Product: IDX Broker
Party: Alice Agent ─── PartyProduct (role: agent) ────┘

Developer Partner Managing Client:

Party: Natalie More ───────── PartyProduct (role: owner) ──────────┐
                                                                    │
Party: BulletProof Real Estate ── PartyProduct (role: developer_partner) ──▶ ProductAccount: #60869

User — "How Do They Log In?"

An application login account linked to Auth0. Separates authentication from identity — not every Party needs to log in (imported agents, offices, MLSs don't).

The user's name is NOT stored on User — it lives on the Party. Access via $user->party->first_name.

Product & ProductAccount

Product is a product offering in our portfolio:

ProductAccount is a specific instance of a product subscription:

ProductAccount
├── product_id: 1 (IDX Broker)
├── product_account_id: 60869
├── product_account_id_type: int
└── billing_account_id → BillingAccount

Customer View

The customers table is a database view (not a physical table) that aggregates data across Party, ProductAccount, BillingAccount, and Product into a flat read-only representation. Useful for listing/searching customers without complex joins.

The Customer model includes a product-aware account() relationship — when product_name is "IDX Broker", it resolves to the IDX Broker clientInfo table via product_account_id → accountID.

IDX Broker Integration

Fusion connects to the existing IDX Broker system through several touch points:

1. Separate Database Connection — idx_connection connects to the IDX Broker MySQL database
2. IDX Client Model (app/Models/IDX/Client.php) — reads from the clientInfo table
3. ProductAccount — product_account_id maps to IDX Broker's accountID
4. PartyIdentifier — stores idx_id for MLS parties (e.g., b001 for SWFLGC MLS)
5. Customer View — aggregates Party + ProductAccount + IDX Client data for display

Billing Module

BillingProvider

An external billing system we integrate with. Currently Zuora is the sole provider.

BillingProvider
├── code: "zuora"
├── name: "Zuora"
└── is_active: true

BillingAccount — "How Does Billing Work?"

Links a Party to a billing provider with billing configuration. Tracks the billing relationship, external IDs, and preferences.

Billing Types

Each billing type maps to different Zuora account settings:

BillingAccount Fields

Related Billing Models

Subscriptions Module

The Subscriptions module is the local system of record for subscription data. While Zuora is the source of truth for billing, Fusion maintains a synced copy of subscription state to enable:

• Fast API responses without hitting Zuora on every request
• Business rule enforcement for rate plan changes
• Local querying of subscription data across the platform

Subscription — "What Are They Subscribed To?"

A subscription belongs to a BillingAccount and contains SubscriptionItems (individual charges).

Subscription
├── billing_account_id → BillingAccount
├── external_subscription_id → Zuora subscription ID
├── status: active, cancelled, suspended, pending
├── current_term_start / current_term_end
├── synced_at → Last sync timestamp (freshness check)
└── items[] → SubscriptionItem (the actual charges)

SubscriptionItem — "What Charges Are On This Subscription?"

Each item represents a single charge/rate plan on the subscription.

Active items have effective_end_date = null. When a rate plan is removed from Zuora, the corresponding item gets an effective_end_date set.

Product Catalog: Rate Plan Groups

The product catalog organizes Zuora rate plans into groups that define selection behavior and dependencies. This is the "Fusion group method" — it maps Zuora's flat catalog into a structured, rule-enforced UI.

RatePlanGroup

Groups organize rate plans for a product with selection rules:

ProductRatePlan

Individual rate plans from the Zuora catalog, mapped to local groups:

How Groups Work — Example

Product: IDX Broker
│
├── RatePlanGroup: "Plan Tier" (selection_mode: one, is_required: true)
│   ├── ProductRatePlan: "IDX Broker Lite" (Monthly)
│   ├── ProductRatePlan: "IDX Broker Core" (Monthly) ← is_default
│   └── ProductRatePlan: "IDX Broker Platinum" (Monthly)
│
├── RatePlanGroup: "Add-Ons" (selection_mode: many, requires_group: "Plan Tier")
│   ├── ProductRatePlan: "Social Pro" (requires: "IDX Broker Core")
│   └── ProductRatePlan: "Home Valuation"
│
└── RatePlanGroup: "MLS Fees" (selection_mode: many, requires_group: "Plan Tier")
    ├── ProductRatePlan: "SWFLGC MLS Fee"
    └── ProductRatePlan: "CRMLS Fee"

Selection rules enforced by SubscriptionAmendmentService:

• Exclusive groups (selection_mode: one): Selecting a new plan auto-swaps the existing one. You can't have both "Core" and "Platinum" — choosing Platinum replaces Core.
• Multi-select groups (selection_mode: many): Multiple plans can be active simultaneously. You can have both "Social Pro" and "Home Valuation" add-ons.
• Required groups (is_required: true): You cannot remove the last plan from a required group. The customer must always have a plan tier.
• Group dependencies (requires_group_id): "Add-Ons" requires "Plan Tier" — you can't add an add-on if no plan tier is active. Removing all plans from "Plan Tier" cascades removal of dependent group items.
• Rate plan dependencies (requires_rate_plan_id): "Social Pro" requires "IDX Broker Core" — if Core is swapped to Lite, Social Pro is automatically removed.

ProductPricing

Each rate plan has pricing entries (charges):

MlsFeeMapping

Maps MLS codes to Zuora rate plans for per-MLS billing:

Subscription Amendment Service

The SubscriptionAmendmentService is the single entry point for all subscription rate plan changes. It orchestrates business rules that the underlying actions are intentionally unaware of.

Operations

Safety Guarantees

• Idempotent: Adding an already-active plan is a no-op. Removing a missing plan is a no-op.
• Cascading removals: Removing a plan that other plans depend on cascades the removal.
• Exclusive group enforcement: Adding to an exclusive group auto-swaps the existing plan.
• Required group protection: Cannot remove the last plan from a required group.
• Mutation safety: All mutations go through SubscriptionMutationGuard which validates subscription state and acquires a lock before executing.

Mutation Guard

Every subscription mutation passes through the SubscriptionMutationGuard:

SubscriptionMutationGuard
├── SubscriptionStateValidator.preCheck() → Quick validation (is subscription active?)
├── SubscriptionLockService.executeWithLock() → Acquires advisory lock
└── SubscriptionStateValidator.validateForMutation() → Full validation under lock

Subscription Sync Flow

Fusion keeps local subscription data fresh by syncing from Zuora on demand:

1. API request hits SubscriptionController
2. SyncAccountSubscriptions checks freshness (configurable, default 5 min)
3. If stale → calls SubscriptionProviderContract.getSubscriptionsForAccount()
4. ZuoraAdapter queries Zuora API with expanded rate plans and charges
5. SubscriptionMapper converts Zuora response → provider-agnostic SubscriptionDetailsData
6. SyncSubscription.syncFromData() upserts local Subscription + SubscriptionItems
7. Items no longer present in Zuora get terminated (effective_end_date set)

Zuora Module

The Zuora module is a pure adapter — it implements two contracts from other modules and converts between Zuora's API format and Fusion's provider-agnostic data objects.

Contracts Implemented

Mappers

Key Design Decision: Provider Agnostic

All data flowing between modules uses provider-agnostic data objects (SubscriptionDetailsData, RatePlanData, RatePlanChargeData, etc.). If Zuora were replaced with another billing provider, only the Zuora module would change — the Billing and Subscriptions modules would remain untouched.

Customer Provisioning

CreateCustomerAccount Flow

When a new IDX Broker customer is created, CreateCustomerAccount orchestrates the full provisioning:

CreateCustomerAccount
├── CreateMlsParty      → Party (type: system, subtype: mls) + PartyIdentifier (idx_id)
├── CreateOfficeParty    → Party (type: org, subtype: office) + PartyIdentifier (office_id)
├── CreateDeveloperPartner → Party (type: org, subtype: developer_partner) + owner Party
├── CreateAgentParty     → Party (type: person, subtype: agent) + identifiers + group memberships
├── CreateUser           → User (auth0_sub, email, party_id)
├── CreateTenant         → Tenant + party_tenant links (legacy, being phased out)
├── CreateProductAccount → ProductAccount + BillingAccount + tenant_products link
└── PartyGroup           → agent added to developer partner's client group

ProvisionCustomer (Batch Import)

For bulk imports, ProvisionCustomer provides a streamlined path:

ProvisionCustomer
├── Get or create Party
├── Find Product by name
├── Ensure BillingAccount (if Zuora ID provided)
├── Create ProductAccount with billing_account_id
└── Link Party → Product → ProductAccount via party_product

Complete Data Flow — Real-World Example

Natalie More: Individual Agent with Developer Partner

User (nataliejmore@gmail.com)
│   auth0_sub: "auth0|6762de3a385c95f62d29e2cf"
│
└──▶ Party: Natalie More (person/agent)
        │
        ├── PartyIdentifier
        │     ├── source: SWFLGC MLS (b001)
        │     ├── type: "member_id"
        │     └── external_id: "26563084"
        │
        ├── PartyGroupMember
        │     ├── group: "Realty One Group MVP Agents" (role: member)
        │     └── group: "BulletProof Clients" (role: client)
        │
        ├── PartyProduct (role: owner)
        │     ├── Product: IDX Broker
        │     └── ProductAccount: #60869
        │           └── billing_account_id → BillingAccount
        │
        ├── BillingAccount
        │     ├── billing_provider: Zuora
        │     ├── external_account_id: "8a3694b893d3e0000193da3422b80bb9"
        │     ├── billing_type: client_direct
        │     └── status: active
        │     │
        │     └── Subscription (synced from Zuora)
        │           ├── status: active
        │           ├── SubscriptionItem: "IDX Broker Core" ($49.99/mo, recurring)
        │           └── SubscriptionItem: "SWFLGC MLS Fee" ($10.00/mo, recurring)
        │
        └── PartyRole
              ├── role_type: "listing_agent"
              ├── subject_type: "listing"
              └── subject_id: "2025017196"

Developer Partner: BulletProof Real Estate Agent

Party: BulletProof Real Estate Agent (org/developer_partner)
│
├── BillingAccount
│     ├── billing_provider: Zuora
│     ├── external_account_id: "8a368af09222dcf101922ad92eb127b2"
│     ├── billing_type: aggregate
│     └── bill_cycle_day: 25
│
├── PartyGroup: "BulletProof Clients"
│     ├── BulletProof Real Estate Agent (role: admin)
│     ├── Natalie More (role: client)
│     └── Bob Smith (role: client)
│
├── PartyProduct (role: developer_partner)
│     └── ProductAccount: #60869 (Natalie's account — admin access)
│
└── PartyGroup: "BulletProof Team"
      ├── BulletProof Real Estate Agent (role: admin)
      └── Anthony Colletti (role: member)
            └── User: webteam@bulletproofrealestateagent.com

Complete Data Flow Diagram

flowchart TD
    subgraph auth [Authentication]
        Auth0[Auth0 IdP]
    end

    subgraph app [Application]
        User[User<br/>auth0_sub, party_id]
    end

    subgraph identity [Identity Module]
        Party[Party<br/>type, name]
        PartyId[PartyIdentifier<br/>MLS IDs, idx_id]
        PartyGroup[PartyGroup<br/>named groups]
        PartyGroupMember[PartyGroupMember<br/>role, status]
        PartyRole[PartyRole<br/>listing_agent]
    end

    subgraph products [Products]
        PartyProduct[PartyProduct<br/>role: owner/agent/admin]
        Product[Product<br/>IDX Broker, OE, etc.]
        ProductAccount[ProductAccount<br/>#60869]
    end

    subgraph billing [Billing Module]
        BillingProvider[BillingProvider<br/>Zuora]
        BillingAccount[BillingAccount<br/>billing_type, status]
        Invoice[Invoice]
        PaymentMethod[PaymentMethod]
    end

    subgraph subscriptions [Subscriptions Module]
        Subscription[Subscription<br/>status, term dates]
        SubItem[SubscriptionItem<br/>name, amount, charge_type]
        RatePlanGrp[RatePlanGroup<br/>selection_mode, dependencies]
        ProdRatePlan[ProductRatePlan<br/>catalog entries]
        AmendmentSvc[SubscriptionAmendmentService<br/>add, remove, swap]
    end

    subgraph zuora [Zuora Module]
        ZuoraAdapter[ZuoraAdapter<br/>BillingProvider + SubscriptionProvider]
        Mappers[Mappers<br/>Account, Subscription, Invoice, Product]
    end

    subgraph business [Business Objects — Future]
        Listing[Listings]
        Transaction[Transactions]
    end

    Auth0 --> User
    User --> Party
    Party --> PartyId
    Party --> PartyGroupMember
    PartyGroupMember --> PartyGroup
    Party --> PartyRole
    Party --> PartyProduct
    Party --> BillingAccount

    PartyProduct --> Product
    PartyProduct --> ProductAccount
    ProductAccount --> BillingAccount
    BillingAccount --> BillingProvider
    BillingAccount --> Invoice
    BillingAccount --> PaymentMethod
    BillingAccount --> Subscription
    Subscription --> SubItem

    Product --> RatePlanGrp
    RatePlanGrp --> ProdRatePlan
    AmendmentSvc --> Subscription

    ZuoraAdapter --> BillingAccount
    ZuoraAdapter --> Subscription
    Mappers --> ZuoraAdapter

    PartyRole --> Listing
    PartyRole --> Transaction

Table Specifications

parties

party_identifiers

party_groups

party_group_members

Unique constraint: (party_group_id, party_id)

party_roles

party_product

users

billing_providers

billing_accounts

Unique constraint: (billing_provider_id, external_account_id)

subscriptions

subscription_items

rate_plan_groups

product_rate_plans

product_pricing

mls_fee_mappings

Reference Data

party_types

party_subtypes

role_types

party_group_roles (conventions)

product_account_roles

billing_types

subscription_statuses

charge_types

selection_modes

Why This Architecture?

Key Principles

Glossary

GraphQL API

The GraphQL schema is organized by resource:

graphql/
├── schema.graphql              # Root schema
├── shared/                     # Common interfaces and error types
├── user/                       # User queries and mutations
├── party/                      # Party CRUD, type queries
├── product/                    # Product queries
└── party-group/                # Party group queries and mutations

Key operations:

• party(id) / parties — Query parties with type/subtype filtering
• createParty / updateParty — Party CRUD
• subscribePartyToProduct — Link a party to a product
• createPartyGroup — Create a new party group
• addPartyToGroup — Add a party to a group with role/status
• partyTypes / partySubtypes / products — Reference data queries

REST API

The Subscriptions module exposes REST endpoints:

References

• RESO Data Dictionary (Real Estate Standards Organization)
• Salesforce Party Model
• SAP Business Partner Model
• Auth0 Laravel SDK Documentation
• Zuora API Documentation

Document Status: Active / Implemented

Completed

1. Identity Module — Party model with types, subtypes, identifiers, groups, roles
2. PartyGroup and PartyGroupMember for flexible party organization
3. Billing Module — BillingAccount, BillingProvider, Invoice, Payment, PaymentMethod
4. Subscriptions Module — Subscription, SubscriptionItem with Zuora sync
5. Product Catalog — RatePlanGroup, ProductRatePlan, ProductPricing, MlsFeeMapping
6. SubscriptionAmendmentService with group enforcement and cascading dependencies
7. Zuora Module — Full adapter with mappers for accounts, subscriptions, invoices, catalog
8. GraphQL API for parties, groups, products
9. REST API for subscriptions with sync-on-demand
10. Customer provisioning (single and batch import)
11. Product catalog sync command (fusion:sync-product-catalog)

Next Steps

1. Build out CRM features on Party foundation
2. Implement Contact/Lead routing service using subscription data
3. Implement MLS data import using Party model
4. Event-driven architecture with Pub/Sub for cross-product communication