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

Each organisation contains applications, and every application isolates its own platform connections, users, and events:

flowchart TB
    subgraph Org["Organisation"]
        subgraph App["Application"]
            PC["Platform Connections<br/>WhatsApp · Telegram · Slack"]
            Users["Users & Identities"]
            Events["Events & Edges"]
        end
    end

Within an application, everything is connected in a graph: events link to users and files through typed edges. See Edges for that model.

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 → Identity)<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 → Identity)"]
    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`
Identity	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`