Integration Patterns — Cross-Cutting Synthesis

Key Takeaways

1. All inter-service communication follows 3 patterns: GraphQL (synchronous queries/mutations), REST (webhooks + file uploads), and RabbitMQ (async events). No shared database backdoors found across 7 domains + infrastructure (H6 validated L1).
2. RabbitMQ is the nervous system — 70+ message types discovered across 7 domains, all using core-lib MessageSender/MessageHandler. Contracts are discoverable from code (H12 validated L1). Every domain publishes and consumes messages.
3. Keycloak is the universal dependency — All 28+ production services validate JWT tokens against the same Keycloak issuer URI. Any Keycloak migration affects everything simultaneously.
4. External APIs are concentrated in 5 services — Stripe (payments), Mux (video), Twilio (SMS), Mandrill (email), Zoom (webinar). All other services have zero external dependencies beyond Keycloak and infrastructure (PostgreSQL, RabbitMQ, Redis).
5. Frontend calls 24+ GraphQL gateways — Both peeq-mono and frontends talk to the same backend services via Istio path-based routing (/api/{service}). ~17% of API calls target non-existent prod services (dead code).

Migration Decision Question

What are the system-wide integration patterns and data model constraints?

System-Wide Service Dependency Map

graph TD
    subgraph "Frontend Layer"
        PM[peeq-mono<br/>Fan App]
        FE[frontends<br/>Admin + Expert]
    end

    subgraph "Identity"
        KC[Keycloak 26.3<br/>OAuth2/OIDC]
        USR[Users]
        CEL[Celebrity]
        FAN[Fan]
    end

    subgraph "Content & Media"
        CON[Content]
        MED[Media]
        WEB[Webinar]
    end

    subgraph "Events & Commerce"
        SHO[Shoutout]
        SHO_BPM[Shoutout BPM]
        INV[Inventory]
        CC[Class-Catalog]
        OSE[Onsite-Event]
    end

    subgraph "Payment"
        STR[Stripe Service]
        SUB[Subscriptions]
        BPM[Purchase-Request BPM]
        WAL[Wallet]
        TXN[Transaction]
    end

    subgraph "Communication"
        EMAIL[Email]
        SMS[SMS]
        NOTIF[Notifications]
        CHAT[Chat]
        MB[Message-Board]
        SSE[SSE]
    end

    subgraph "Supporting"
        TAGS[Tags]
        SEARCH[Search]
        TRACK[Tracking]
        REPORT[Reporting]
        ORG[Org-Manager]
        GP[Group-Profile]
        JRN[Journey]
    end

    subgraph "External APIs"
        STRIPE_API[Stripe API]
        MUX_API[Mux API]
        TWILIO_API[Twilio API]
        MANDRILL_API[Mandrill API]
        ZOOM_API[Zoom API]
        STREAM_API[Stream Chat API]
        GCS_API[Google Cloud Storage]
    end

    subgraph "Infrastructure"
        PG[(PostgreSQL<br/>35 DBs)]
        RMQ[RabbitMQ<br/>3-node cluster]
        REDIS[(Redis)]
        NFS[(NFS Storage)]
    end

    %% Frontend → Backend
    PM -->|GraphQL| USR & CEL & FAN & CON & MED & WEB & SHO & INV & CC & STR & SUB & WAL & TXN & NOTIF & CHAT & MB & SSE & TAGS & JRN & ORG & GP
    FE -->|GraphQL| USR & CEL & FAN & CON & MED & WEB & SHO & INV & CC & STR & SUB & WAL & TXN & NOTIF & CHAT & MB & SSE & TAGS & EMAIL & SMS & JRN & ORG & GP

    %% External APIs
    STR -->|REST| STRIPE_API
    CON & MED -->|REST| MUX_API
    SMS -->|SDK| TWILIO_API
    EMAIL -->|SDK| MANDRILL_API
    WEB -->|REST| ZOOM_API
    CHAT -->|SDK| STREAM_API
    MED -->|REST| GCS_API

    %% All services → Keycloak
    USR & CEL & FAN & CON & MED & WEB & SHO & INV & CC & STR & SUB & WAL & TXN & EMAIL & SMS & NOTIF & CHAT & MB & SSE & TAGS & SEARCH & TRACK & REPORT & ORG & GP & JRN & OSE -->|JWT| KC

Synchronous Communication (GraphQL + REST)

Service-to-Service GraphQL Calls

REST Endpoints (External Webhooks)

Cross-Domain Dependency Matrix

                    Identity  Content  Events  Payment  Comms  Support  Infra
Identity              ●                  →                       →
Content               →         ●        →                       →
Events                →         →        ●       ←       ←       →
Payment               →                  →       ●       ←       →
Communication         →                  →       →       ●
Supporting            ←                  ←       ←               ●
Infrastructure        ←         ←        ←       ←       ←       ←        ●

● = internal   → = calls   ← = called by

Key coupling hotspot: Inventory service is called by 5 different domains (Stripe, Subscriptions, Transaction, Shoutout, Webinar). It’s the cross-cutting product catalog hub.

Asynchronous Communication (RabbitMQ)

Complete Message Contract Inventory

Compiled from all 7 analyzed domains. All follow core-lib MessageSender/MessageHandler pattern.

Identity Domain (Sessions 2)

Content & Streaming Domain (Session 3)

Payment Domain (Sessions 4-5)

Events Domain (Session 6)

Communication Domain (Session 7)

Message Flow Patterns

graph LR
    subgraph "Product Lifecycle"
        SUB[Subscriptions] -->|SubscriptionCreated| STR[Stripe]
        CC[Class-Catalog] -->|JourneyCreated| STR
        INV[Inventory] -->|ItemCreated| STR
        STR -->|ProductCreated| SUB & INV
    end

    subgraph "Purchase Flow"
        INV -->|PurchaseRequested| BPM[Purchase BPM]
        BPM -->|CreateTransaction| WAL[Wallet]
        WAL -->|TransactionCreated| BPM
        BPM -->|UpdatePurchaseState| INV
        BPM -->|SendEmail| EMAIL[Email]
    end

    subgraph "Notification Pipeline"
        ANY[Any Service] -->|Event| NOTIF[Notifications]
        NOTIF -->|SendEmail| EMAIL
        NOTIF -->|SendSms| SMS
        NOTIF -->|SendSse| SSE[SSE]
    end

    subgraph "Real-time Updates"
        CEL[Celebrity] -->|CreateSseGroup| SSE
        FAN[Fan] -->|AddToSseGroup| SSE
        WAL -->|SendSse| SSE
        MB[Message-Board] -->|PostCreated| SSE
    end

RabbitMQ Statistics

External API Inventory

Active External Dependencies

Inactive External Dependencies (Retire)

API Key Migration Impact

For any infrastructure migration, these API keys must be migrated: - GCP Secret Manager: Already centralized (20+ secret modules in Terraform) - Stripe webhook URL: Must be updated in Stripe dashboard if service URL changes - Mux webhook URLs: Must be updated in Mux dashboard (2 services receive webhooks) - Zoom webhook URL: Must be updated in Zoom Marketplace app - All keys per tenant: 4 production tenants × 11 active integrations = ~44 key sets

Database-per-Service Architecture

Complete Database Inventory

35 PostgreSQL databases per tenant, all accessed via PgBouncer:

Note: Databases marked “—” for migrations/tables were not deeply analyzed (supporting domain, deferred to Session 10+).

Schema Complexity Ranking

Cross-Database References

No foreign key constraints exist between databases (correct for microservices). Cross-references use:

Shared Database (Exception)

Email, SMS, and Notifications share peeq-notification-service-db. This is the only shared database discovered across 7 domains. It’s an intentional design — notifications orchestrate email and SMS delivery.

Delta Check: Early Assumptions vs Later Findings

Per the plan, re-validating Sessions 1-3 assumptions against Sessions 4-8 findings.

Session 1 (Frontend) — Validated

Session 2 (Identity) — Validated with additions

Session 3 (Content) — Validated

Hypothesis Status Summary (Post-Session 9)

Key Integration Risks for Migration

1. Keycloak Migration (Affects Everything)

Any change to Keycloak (URL, realm, JWT claims) requires coordinated update to all 28+ services. This is the single highest-risk integration point.

2. Inventory Service (Cross-Domain Hub)

Inventory is called by 5 domains. Any schema or API changes to inventory ripple across payment, events, and content. Must be migrated carefully or kept stable during other migrations.

3. BPM Engine (In-Flight State)

Two BPM engines (purchase-request-bpm, shoutout-bpm) have running process instances. Migration requires draining active instances before engine replacement.

4. External Webhook URLs (4 Services)

Stripe, Mux (×2), and Zoom webhook URLs must be updated if service endpoints change during migration. Webhook delivery failures during migration = lost events.

5. Notification Pipeline (Fan-Out)

Notifications → Email/SMS/SSE pipeline is the primary fan-out mechanism. Breaking this pipeline affects all user-facing notifications across the platform.

Last updated: 2026-01-30 — Session 9 Review by: 2026-04-30 Staleness risk: Medium — integration patterns are stable but message contracts may evolve