Skip to main content

Core Concepts

This page defines key terms and concepts you'll encounter throughout Staqr. Refer back here when you need clarification on terminology.

Entities & Data Model​

Staqr manages telecommunications services through a hierarchical entity model. Understanding this hierarchy is essential for navigating the platform.

Entity Hierarchy​

Platform (Staqr multi-tenant)
  └── Seller (brand/reseller - NOT a tenant)
        └── Customer (CRM contact)
              └── CustomerAccount (account receivable)
                    └── BillingAccount (billing entity)
                          └── UserAccount (service user)
                                └── Subscription (service subscription)
                                      └── ServiceInstance (active service)

Seller​

A Seller is a brand or reseller within a Staqr platform. It's a grouping construct for organizing customers, not a separate tenant.

Key Points:

  • Multiple sellers can exist in one platform
  • Sellers can have parent-child relationships (reseller hierarchies)
  • Used for multi-brand management, commission tracking, regional organization
  • Sellers do NOT have their own database schemas or data isolation

Example: A telco reseller "FastMobile" is a Seller under the Fastter platform.

Customer​

A Customer is a CRM contact - a person or business that purchases telecommunications services.

Key Points:

  • Belongs to a Seller
  • Can have multiple Customer Accounts (billing entities)
  • Tracked with VIP status, churn risk, complaints, hardship flags

Example: John Smith is a Customer of FastMobile with ID CUST-00001.

Customer Account​

A Customer Account is an account receivable entity linking a customer to their billing accounts.

Status Values: ACTIVE, CLOSE

Example: John Smith's account JohnSmithAcct under CUST-00001.

Billing Account​

A Billing Account is the billing entity that groups subscriptions and generates invoices.

Status Values: ACTIVE, CANCELED, TERMINATED, CLOSED

Key Points:

  • One customer can have multiple billing accounts (e.g., personal + business)
  • Invoices are generated at this level
  • Dunning workflows apply here

Example: John's personal billing account BA-12345.

User Account​

A User Account represents a service user within a billing account.

Status Values: ACTIVE, CANCELED, TERMINATED, CLOSED

Example: John's mobile service user account UA-67890.

Subscription​

A Subscription is a purchased telecommunications service (e.g., mobile plan, broadband).

Status Values: CREATED, ACTIVE, CANCELED, RESILIATED, CLOSED, SUSPENDED, PENDING

Key Points:

  • Billing type: PREPAID or POSTPAID
  • Has a service plan (price plan, charges, bundles)
  • One subscription can have multiple service instances

Example: John's $50/month mobile plan with 50GB data.

Service Instance​

A Service Instance is an active service component (e.g., a phone number, SIM card).

Status Values: ACTIVE, INACTIVE, CANCELED, TERMINATED, SUSPENDED, CLOSED, PENDING

Example: John's mobile number 0412345678 on his subscription.

Workflow & Automation​

Flow​

A Flow is a workflow automation that executes when triggered.

Components:

  • Trigger: What starts the flow (schedule, webhook, event)
  • Actions: What happens when triggered (code, integrations, logic)

Example: A flow that sends a welcome SMS when a new customer activates.

Connection​

A Connection securely stores credentials for integrating with external services.

Types:

  • OAuth2 (e.g., Google, Slack)
  • API Key (e.g., Twilio, Stripe)
  • Username/Password (legacy systems)

Example: A Twilio connection storing API credentials for sending SMS.

Integration (Piece)​

An Integration (also called a "Piece") is a pre-built connector to an external service.

Examples: Slack integration, Google Sheets integration, Stripe integration.

Key Points:

  • 100+ pre-built integrations available
  • Custom integrations can be built with TypeScript SDK
  • Each integration has triggers and actions

Architecture​

Multi-Tenant Architecture​

Staqr supports full multi-tenancy with clear separation between Platform tenants and Seller groupings.

Platform = Top-level tenant isolation

  • Separate database schema per platform
  • Completely isolated data
  • Own Commerce provider and CCaaS tenant

Seller = Brand/reseller grouping (NOT a tenant)

  • Shares platform database
  • Used for organization and reporting
  • No data isolation between sellers

Users = Role-based access

  • Belong to a seller
  • Permissions via RBAC (Role-Based Access Control)
  • Field-level data masking for PII
┌─────────────────────────────────────────────────────────────────────────┐
│                        MASTER PLATFORM (STAQR)                          │
│                   (Multi-tenant hosting platform)                       │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
    ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
    │ PLATFORM TENANT A │ │ PLATFORM TENANT B │ │ PLATFORM TENANT C │
    │ (Staqr Platform)  │ │ (Staqr Platform)  │ │ (Staqr Platform)  │
    │ = Commerce Provider│ │ = Commerce Provider│ │ = Commerce Provider│
    │ = CCaaS Tenant    │ │ = CCaaS Tenant    │ │ = CCaaS Tenant    │
    └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘
              │                     │                     │
      ┌───────┴───────┐     ┌───────┴───────┐     ┌───────┴───────┐
      │  Seller 1     │     │  Seller A     │     │  Seller X     │
      │  Seller 2     │     │  Seller B     │     │  Seller Y     │
      │  (grouping)   │     │  (grouping)   │     │  (grouping)   │
      └───────────────┘     └───────────────┘     └───────────────┘

Three-Platform Architecture​

Staqr integrates three platform components:

1. Staqr Platform (Node.js/React)

  • UI/UX layer
  • Workflow automation engine
  • API gateway
  • Authentication: JWT tokens

2. Commerce (Java CRM)

  • Billing and subscriptions
  • Customer hierarchy
  • Invoice generation
  • 1500+ API endpoints (V0, V1, V2)
  • Authentication: Keycloak OAuth2

3. CCaaS (Wazo Platform)

  • Contact center infrastructure
  • WebRTC voice/video
  • Call recording
  • 21 Docker services
  • Authentication: CCaaS tokens

Key Distinction:

  • Frontend calls Staqr API (JWT auth)
  • Staqr API proxies to Commerce and CCaaS
  • Never call Commerce/CCaaS directly from frontend

Regulatory Compliance (Australian Telco)​

Australian telecommunications regulations require specific protections. Staqr implements these at the platform level.

HRT (High-Risk Transaction)​

High-Risk Transactions are sensitive operations that require additional authentication (MFA).

HRT-Protected Operations:

  • Port-out (number porting to another carrier)
  • Suspension
  • Termination
  • SIM swap
  • Payment method changes

Levels:

  • STANDARD: MFA challenge required
  • ELEVATED: SMS two-way verification (30-min window)

PPV (Pre-Port Validation)​

Pre-Port Validation is ACMA-mandated SMS verification for number porting (since September 2020).

Process:

  1. Customer requests port-out to new carrier
  2. Losing carrier sends SMS to device: "Reply YES to port your number"
  3. Customer must reply within 30 minutes
  4. 3-strike rule: Max 3 attempts per port request

Bypass Conditions: Stolen device, suspended number, customer overseas (requires 2x Category A ID).

TCP Code​

Telecommunications Consumer Protections Code (ACMA) mandates:

  • 10-day disconnection notice
  • 2-day complaint acknowledgment
  • 10-day complaint resolution (or escalate to TIO)
  • CIS (Critical Information Summary) for all plans

DV Protection​

Domestic Violence Protection (ACMA DFSV Standard 2025) provides:

  • Service continuity for victims
  • No contact with perpetrator
  • Safe communication channels
  • Hidden call records

Status: Coming July 2025.

TIO​

Telecommunications Industry Ombudsman - independent dispute resolver.

Obligations:

  • 2-day urgent complaint resolution
  • 10-day standard complaint resolution
  • Escalate unresolved complaints to TIO
  • TIO contact: 1800 062 058

Billing Concepts​

Prepaid vs Postpaid​

Level: Subscription-level (NOT customer-level)

Prepaid:

  • Pay before using service
  • Uses wallet balance
  • No invoices
  • Top-up to add funds

Postpaid:

  • Use service first, pay later
  • Generates invoices
  • Billing cycles (monthly, etc.)
  • Credit checks required

Note: One customer can have BOTH prepaid and postpaid subscriptions.

Invoice States (9-State Architecture)​

Commerce uses 9 invoice payment states (not simple PAID/UNPAID):

StateDescription
NONENo payments received
PARTIALPartial payment
FULLFully paid
OVERPAIDOverpayment (credit balance)
PENDING_PAYMENTPayment processing
SUSPENDEDPayment suspended
DUNNINGIn dunning process
WRITTEN_OFFBad debt write-off
CLOSEDInvoice closed

Journeys​

Journey Pattern​

A Journey is a guided multi-step workflow in the UI (wizard pattern).

Common Journeys:

  • Activation: New customer/subscription setup
  • Porting: Number port-in from another carrier
  • SIM Swap: Replace physical SIM
  • eSIM: Provision digital SIM
  • MSN Swap: Change mobile number
  • Plan Change: Upgrade/downgrade subscription
  • Suspension: Temporarily suspend service
  • Termination: Permanently cancel service

Components:

  • Multiple steps (customer select, config, verification, confirmation)
  • HRT protection for high-risk operations
  • AI Assistant integration for help

AI & Assistant​

AI Assistant​

Context-aware AI help available on every page.

Capabilities:

  • Answer questions about current page/entity
  • Suggest next actions
  • Link to relevant documentation
  • Execute tasks via MCP tools

Integration: Uses setPageData() to receive page context.

MCP (Model Context Protocol)​

Protocol for connecting AI tools to Staqr.

Examples:

  • Knowledge base search
  • Customer data lookup
  • Subscription management
  • Invoice generation

Next Steps​

Now that you understand core concepts, explore: