> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Overview

> Understand the core concepts and architecture of Trackly SMS

## Core Concepts

Trackly SMS is organized around several key entities that work together to power your SMS marketing.

### Accounts

An **Account** is your organization's workspace in Trackly SMS. Each account:

* Contains all your data (lists, contacts, campaigns, offers)
* Has its own team members with role-based access (Owner, Member, Viewer)
* Maintains separate API keys and billing
* Can configure account-wide settings like message prepend/append text
* **Free tier**: 500 messages/month with no payment method required

### Sending Lists

A **Sending List** represents a phone number configuration for sending messages. Each list includes:

* A phone number (your "from" number)
* Managed sending, or BYOC (Bring Your Own Carrier) credentials for your existing provider (Twilio, Infobip, CM, Lime)
* A brand name for identification
* Provider-specific credentials and settings

<Note>
  You can have multiple sending lists per account, allowing you to send from different numbers for different brands or use cases.
</Note>

### Contacts

Trackly SMS has a two-tier contact model:

| Entity          | Scope    | Purpose                                             |
| --------------- | -------- | --------------------------------------------------- |
| **Contact**     | Global   | The phone number itself with carrier info           |
| **ListContact** | Per-list | Subscription state and activity for a specific list |

A single phone number can be subscribed to multiple lists across different accounts. Each subscription tracks:

* Subscription status (active/unsubscribed)
* Signup method and date
* Custom fields you define
* Activity stats (sends, clicks, revenue)

### Audiences

An **Audience** is a segment of contacts defined by filter conditions. Build segments using:

<CardGroup cols={2}>
  <Card title="Time-Based" icon="clock">
    Last sent, last clicked, signup date
  </Card>

  <Card title="Count-Based" icon="hashtag">
    Send count, click count
  </Card>

  <Card title="Custom Fields" icon="tag">
    Any field you've defined on contacts
  </Card>

  <Card title="Revenue" icon="dollar-sign">
    Has converted, total revenue, average revenue
  </Card>
</CardGroup>

Audiences support complex AND/OR logic with nested groups for sophisticated targeting.

### Creatives

A **Creative** is a reusable message template. Each creative contains:

* Message body with dynamic link placeholders (`{{link1}}`, `{{link2}}`)
* Offer bindings for each link
* SMS segment count calculation
* Status (active, paused, archived)
* Performance metrics (sends, clicks, revenue)

### Schedules

A **Schedule** is a campaign configuration. Trackly supports two send modes:

<Tabs>
  <Tab title="Blast Mode">
    Full editorial control:

    * Create multiple message variants
    * Set audience percentage splits per variant
    * Choose specific offers for each variant
    * Include MMS images
  </Tab>

  <Tab title="Automated Mode">
    AI-driven optimization:

    * Machine learning selects the best creative per contact
    * Models trained on click and revenue data
    * Continuous improvement from performance feedback
    * Configure what percentage uses automated selection
  </Tab>
</Tabs>

Schedules support one-time sends or recurring patterns with day-of-week selection.

### Welcome Journeys

A **Welcome Journey** is an automated sequence triggered when contacts join your lists. Journeys consist of steps:

| Step Type        | Purpose                                         |
| ---------------- | ----------------------------------------------- |
| **Send Message** | Deliver a specific creative                     |
| **Wait**         | Pause for a duration (minutes, hours, days)     |
| **Condition**    | Branch based on click behavior or custom fields |
| **Exit**         | End the journey for this contact                |

### Offers

An **Offer** represents an affiliate offer from your network. Offers include:

* External platform sync (TUNE, Everflow, or manual)
* Tracking URLs
* Payout information (CPA, CPC)
* Performance statistics

## Data Flow

Here's how data flows through the platform:

```mermaid theme={null}
graph TD
    A[Contact Added to List] --> B{Journey Trigger?}
    B -->|Yes| C[Enroll in Journey]
    B -->|No| D[Wait for Campaign]
    C --> E[Process Journey Steps]
    D --> F[Schedule Matches Audience]
    E --> G[Queue Message]
    F --> G
    G --> H[Execute Send]
    H --> I[Create Short Links]
    I --> J[Deliver via Provider]
    J --> K[Track Clicks]
    K --> L[Attribute Revenue]
```

## Team Roles

Trackly SMS supports three roles with different permission levels:

| Role       | API Keys           | Team Management         | Sending | View Reports |
| ---------- | ------------------ | ----------------------- | ------- | ------------ |
| **Owner**  | Create/View/Delete | Add/Remove/Change roles | Yes     | Yes          |
| **Member** | No                 | View only               | Yes     | Yes          |
| **Viewer** | No                 | View only               | No      | Yes          |

<Info>
  Multiple owners are allowed per account. Every account must have at least one owner.
</Info>

## Architecture Overview

Trackly SMS consists of several services:

<AccordionGroup>
  <Accordion title="Dashboard (Cloud Run)">
    React-based web application for campaign management, reporting, and account settings. All user interactions happen here.
  </Accordion>

  <Accordion title="API Service (Cloud Run)">
    Flask REST API powering the dashboard and providing programmatic access via API keys.
  </Accordion>

  <Accordion title="External API (Cloud Run)">
    Public-facing API for sending messages and managing contacts programmatically.
  </Accordion>

  <Accordion title="Message Executor (VM)">
    High-throughput polling worker that processes the message queue and sends via your configured SMS providers.
  </Accordion>

  <Accordion title="Link Tracking Service (Cloud Run)">
    Low-latency redirect service for tracking link clicks with bot detection.
  </Accordion>

  <Accordion title="Job Server (VM)">
    Background job processor for tasks like ML model training, LTV calculations, and data syncing.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="5-Minute Quickstart" icon="rocket" href="/getting-started/quickstart">
    Send your first message
  </Card>

  <Card title="Data Model Deep Dive" icon="diagram-project" href="/concepts/data-model">
    Understand entity relationships
  </Card>
</CardGroup>