Core Concepts#

Understanding Outeract’s architecture and data model is essential for building effective integrations. This section covers the fundamental concepts that power the platform.

The Big Picture#

Outeract is built around a graph-based, event-driven architecture that provides:

Unified Messaging - One API for all messaging platforms
Event Sourcing - Every action is captured as an immutable event
Graph Relationships - Events are connected via edges that track provenance
Multi-Tenancy - Complete data isolation between organizations

flowchart TB
    subgraph Org["Organisation"]
        subgraph App["Application"]
            subgraph Users["Users"]
                User[User]
                PU[Platform User]
            end
            subgraph Events["Events"]
                Event[Event]
                Edges[Edges]
            end
            subgraph PC["Platform Connections"]
                WA[WhatsApp]
                TG[Telegram]
                SL[Slack]
            end
        end
    end
    Event --> User
    Event --> PU
    Event --> Edges
    Edges --> PU

Key Concepts#

Architecture #

How Outeract’s components work together - APIs, webhooks, and platform integrations.

Applications #

The top-level container for your messaging data. Learn about multi-tenancy and data isolation.

Users & Platform Users #

Understand user identity, how users connect across platforms, and the platform user model.

Events #

The core data model. Every message, status update, and action is an event.

Edges #

Graph relationships that connect events, users, and files. Track who sent what to whom.

Conversations #

How messages thread together into conversations, and how to query conversation history.

Data Flow Example#

Here’s how a typical inbound message flows through Outeract:

flowchart TB
    A["1. User sends 'Hello' on WhatsApp"] --> B["2. WhatsApp sends webhook to Outeract"]
    B --> C["3. Outeract creates:<br/>• Event (message.inbound)<br/>• Edge (sent_by → PlatformUser)<br/>• Edge (sent_to → System)"]
    C --> D["4. Your webhook receives the event"]
    D --> E["5. You send a reply via API"]
    E --> F["6. Outeract creates:<br/>• Event (message.outbound)<br/>• Edge (sent_by → System)<br/>• Edge (sent_to → PlatformUser)"]
    F --> G["7. Message delivered to WhatsApp user"]

Quick Reference#

Concept	Description	Key Fields
Organisation	Top-level tenant	`id`, `name`
Application	Messaging container	`id`, `name`, `config`
User	Generic user identity	`id`, `name`, `system_user`
PlatformUser	Platform-specific identity	`external_id`, `platform_connection_id`
Event	Any action/message	`id`, `event_type_id`, `payload`, `status`
Edge	Relationship between entities	`source`, `target`, `edge_type`
PlatformConnection	Configured platform	`id`, `platform_name`, `config`