Glossary¶

Technical terms and concepts used throughout the Expensis automation documentation.

A¶

Addon¶

Mobile service addon (e.g., extra data, international calling) that can be activated or canceled via the Routit Nina API.

Asynchronous Handler¶

MessageBus handler that processes commands asynchronously in the background, allowing non-blocking execution.

B¶

Billing Cycle¶

The period (typically monthly) for which usage and billing are calculated. Usually starts on a specific date each month.

Billing Insight¶

Analytical data about billing patterns, anomalies, cost trends, and usage statistics generated by BillingInsightTotalsHandler.

Bulk Insert¶

Database optimization technique that inserts multiple records in a single query rather than individual inserts. Critical for CDR import performance.

C¶

Calvi¶

T-Mobile's customer portal and API system for managing mobile services and billing data.

CDR (Call Detail Record)¶

Detailed record of a single call, SMS, or data session including date, duration, destination, and cost. Imported from provider APIs and used for billing calculations.

Chain¶

Sequence of commands executed one after another. Commands can attach chains using withChain(). The MessageConsumedHandler automatically executes chained commands after the current command completes.

Example:

$command = new DispatchTotalsCommand(...);
$command->withChain([
    new CalculateTotalsCommand(...),
    new DispatchTotalsBackupCommand(...)
]);

ChainableCommandInterface¶

Interface that commands must implement to support command chaining. Provides withChain() and getChain() methods.

Command¶

An object representing an intent to perform an action. Commands are dispatched to the MessageBus and handled by corresponding handlers.

Example: CalculateTotalsCommand, KpnSp16SyncCommand

Command-Query Responsibility Segregation (CQRS)¶

Architectural pattern that separates read and write operations. Commands modify state, queries read state.

Console Command¶

CLI command that can be executed from the terminal using php bin/console <command-name>.

Example: php bin/console sync:manager

Cron Job¶

Scheduled task that runs automatically at specified intervals using the system cron daemon.

Example: */5 * * * * (every 5 minutes)

Customer¶

Business entity that subscribes to telecom services. Each customer has subscriptions, devices, and billing data.

D¶

Dispatch¶

The act of sending a command to the MessageBus for asynchronous processing.

$this->commandBus->dispatch($command);

Dispatch Point¶

Location in code (controller, service, handler, or console command) where a command is dispatched to the MessageBus.

DispatchTotalsCommand¶

Router command that determines which totals calculation handler should process the request (CalculateTotalsCommand vs CalculateTotalsRateplanCommand).

E¶

EEN (KPN)¶

KPN's Enterprise Ethernet Network platform and portal for business customers.

Event¶

An occurrence in the system that other components can listen to and react to.

Example: WorkerMessageHandledEvent is fired after a handler completes.

Event Subscriber¶

A class that listens for specific events and executes logic when those events occur.

Critical Example: MessageConsumedHandler subscribes to WorkerMessageHandledEvent

F¶

Flatliner¶

A phone number that shows zero usage (no calls, SMS, or data) for a billing cycle. Often indicates inactive or suspended service.

G¶

Grexx¶

Order management system integrated with Expensis for processing telecom orders.

GRIP (KPN)¶

KPN's GRIP platform for managing business telecom services.

H¶

Handler¶

A class that processes a specific command type. Handlers contain the business logic for executing commands.

Naming Convention: {CommandName}Handler

Example: CalculateTotalsCommand → CalculateTotalsHandler

I¶

Import Queue¶

Database table storing pending import jobs to be processed. Used by KPN SP16 and other providers to queue data imports.

Tables: kpn_import_queue, vodafone_import_queue, yielder_queue

IRMA¶

Data source integrated with Expensis for additional telecom data scraping.

Invoice¶

Billing document generated by providers showing charges for a billing cycle. Can be in PDF or data format.

K¶

KPN¶

Major Dutch telecommunications provider with multiple platforms (SP16, EEN, GRIP) integrated with Expensis.

M¶

Master Router¶

Handler that routes commands to other handlers based on context.

Examples: - SyncProfileHandler - Routes to provider-specific sync handlers - DispatchTotalsHandler - Routes to totals calculation handlers

MessageBus¶

Symfony Messenger component that handles asynchronous command dispatch and routing. Acts as the central communication backbone.

MessageConsumedHandler¶

CRITICAL Event subscriber that enables ALL command chaining. Listens for WorkerMessageHandledEvent and automatically dispatches chained commands.

Location: src/MessageBus/MessageConsumedHandler.php

Impact: Single point of failure - if this breaks, all command chains stop working.

N¶

Nina API (Routit)¶

Routit's API for managing mobile addons (activation, cancellation, modification).

O¶

Odido¶

Brand name for Yielder mobile services (formerly known as Yielder, now marketed as Odido).

Orchestrator¶

Component that coordinates multiple operations or workflows.

Example: sync:manager console command orchestrates all provider syncs

P¶

Partner¶

Reseller or business partner who has multiple customer accounts under their umbrella. Used in T-Mobile Calvi structure.

Portation Date¶

Date when a phone number is transferred (ported) from one provider to another.

Provider¶

External telecommunications company (KPN, Vodafone, T-Mobile, Routit, Yielder) whose data is synced into Expensis.

Puppeteer¶

Headless browser automation tool used for web scraping when no API is available.

Used by: PupeteerKpnSp16SyncHandler

R¶

Rate Limit¶

Maximum number of API requests allowed within a time period to prevent abuse.

Example: Nina API allows 10 requests per minute per customer

Rate Plan¶

Pricing structure that defines costs for calls, SMS, and data usage. Applied during totals calculation.

Routit¶

Mobile service provider integrated with Expensis for mobile subscriptions, CDRs, and addon management.

Router¶

See Master Router

S¶

Single Point of Failure (SPOF)¶

Component that, if it fails, causes the entire system or major subsystem to stop functioning.

Expensis SPOFs: 1. MessageConsumedHandler 2. SyncProfileHandler 3. sync:manager cron job

SP16 (KPN)¶

KPN's Service Platform 16, their primary business customer portal and API.

Subscription¶

A contract for telecom services (mobile or fixed-line) associated with a customer and device.

Sync¶

Process of importing data from external provider APIs/portals into the Expensis database.

SyncProfile¶

Database record defining how and when to sync a specific provider for a customer. Includes credentials, sync type, and schedule.

Table: sync_profile

Fields: customer_id, sync_type, active, next_sync_date, credentials

SyncTask¶

Database record tracking a single sync execution. Records status, start/end times, and errors.

Table: sync_task

Statuses: pending, processing, completed, failed, invalid_credentials, invoice_not_yet_available

sync:manager¶

CRITICAL Console command that runs every 5 minutes and orchestrates all automated provider syncs.

Impact: Master orchestrator - if this stops, NO automated syncs occur

T¶

Telfort¶

Telecommunications provider (legacy system) integrated with Expensis.

Totals¶

Aggregated billing data calculated from CDRs, showing total costs, duration, and usage by category.

Table: totals

Totals Backup¶

Historical copy of totals saved for audit and comparison purposes.

Table: totals_backup

V¶

Vodafone¶

Major telecommunications provider integrated with Expensis using My Vodafone portal/API.

W¶

Worker¶

Background process that executes asynchronous MessageBus handlers. Part of Symfony Messenger.

Workflow¶

Complete sequence of operations from trigger to completion, often involving multiple commands and handlers.

Example: Master Sync Workflow, CDR Processing Workflow

WorkerMessageHandledEvent¶

Symfony event fired after a handler completes processing a command. The MessageConsumedHandler subscribes to this event to enable command chaining.

Y¶

Yielder¶

Mobile service provider (now branded as Odido) integrated with Expensis.

Technical Patterns¶

Command Chain¶

Command A → Handler A → Dispatch Command B → Handler B → Dispatch Command C → Handler C

Sync Pattern¶

Sync Provider → Import Data → Calculate Totals → Backup Totals → Save Status

Router Pattern¶

Router Command → Router Handler → Determine Target → Dispatch Target Command

Bulk Insert Pattern¶

foreach ($rows as $row) {
    $batch[] = $row;
    if (count($batch) >= 1000) {
        $this->bulkInsert($batch);
        $batch = [];
        $entityManager->clear();  // Free memory
        gc_collect_cycles();       // Garbage collection
    }
}

Symfony Components¶

AsMessageHandler¶

PHP attribute (annotation) that marks a class as a MessageBus handler.

#[AsMessageHandler]
class ExampleHandler { ... }

EntityManagerInterface¶

Doctrine ORM interface for database operations (persist, flush, queries).

MessageBusInterface¶

Symfony Messenger interface for dispatching commands.

$this->commandBus->dispatch($command);

Database Terms¶

Partition¶

Database table optimization where data is divided into smaller physical segments based on criteria (e.g., by month for CDRs).

Example: call_detail_record table partitioned by month

Index¶

Database optimization structure that speeds up queries on specific columns.

Example: idx_cdr_customer_date on (customer_id, call_date)

Flush¶

Doctrine ORM operation that persists all pending changes to the database.

$this->entityManager->flush();

Clear¶

Doctrine ORM operation that clears the identity map, freeing memory. Essential during bulk operations.

$this->entityManager->clear();

Acronyms¶

Acronym	Full Term
API	Application Programming Interface
CDR	Call Detail Record
CLI	Command Line Interface
CQRS	Command-Query Responsibility Segregation
CRON	Command Run On (scheduled tasks)
EEN	Enterprise Ethernet Network
GRIP	(KPN platform name)
ORM	Object-Relational Mapping
PDF	Portable Document Format
SMS	Short Message Service
SP16	Service Platform 16
SPOF	Single Point of Failure
UI	User Interface
URL	Uniform Resource Locator

System Architecture - How components work together
Key Concepts - Core architectural concepts
Command Index - All console commands
Handler Index - All MessageBus handlers
Workflows - Complete workflow documentation