Overview¶

Welcome to the complete Expensis automation documentation - your comprehensive guide to understanding and working with the billing platform's automation system.

What is Expensis?¶

Expensis is an automated billing platform that: - Syncs data from multiple telecom providers (KPN, Vodafone, T-Mobile, Routit, Yielder) - Imports CDRs (call detail records) and subscription data - Calculates billing totals and costs - Generates invoices and reports - Manages telecom services and devices

Automation Level: 95%+ of operations run automatically without manual intervention

System at a Glance¶

Component	Count	Purpose
Providers Integrated	6	KPN (SP16, EEN, GRIP), Vodafone, T-Mobile, Routit, Yielder
Console Commands	115	CLI management and automation
MessageBus Handlers	36	Async business logic processors
Active Cron Jobs	18	Scheduled automated tasks
Complete Workflows	10	Documented end-to-end processes
CDRs Processed Daily	50k-200k	Call detail records

Architecture Overview¶

graph TB
    subgraph "Entry Points"
        CRON[Cron Jobs<br/>Every 5 min]
        WEB[Web UI<br/>User actions]
        API[External APIs<br/>Provider data]
        CLI[Console<br/>Admin tasks]
    end

    subgraph "Processing Layer"
        MB[MessageBus<br/>Async dispatch]
        HANDLERS[36 Handlers<br/>Business logic]
        EVENTS[Event System<br/>Chain execution]
    end

    subgraph "Data Layer"
        DB[(Database<br/>MySQL)]
        FILES[File Storage<br/>CDRs, reports]
    end

    subgraph "External"
        KPN[KPN APIs]
        VOD[Vodafone API]
        TMO[T-Mobile API]
        ROUT[Routit API]
        YIELD[Yielder API]
    end

    CRON --> MB
    WEB --> MB
    CLI --> MB

    MB --> HANDLERS
    HANDLERS --> EVENTS
    EVENTS --> MB

    HANDLERS --> DB
    HANDLERS --> FILES

    HANDLERS <--> KPN
    HANDLERS <--> VOD
    HANDLERS <--> TMO
    HANDLERS <--> ROUT
    HANDLERS <--> YIELD

    style CRON fill:#ff6b6b
    style MB fill:#4ecdc4
    style EVENTS fill:#95e1d3

How It Works¶

1. Master Sync (Every 5 Minutes)¶

Trigger: Cron job */5 * * * *

sync:manager
  ↓
Query active SyncProfiles
  ↓
For each provider:
  ↓
Dispatch SyncProfileCommand
  ↓
Route to provider handler
  ↓
Import data from provider
  ↓
Calculate billing totals
  ↓
Backup and save

See: Master Sync →

2. Provider Sync Flow¶

ALL provider syncs follow this pattern:

1. SYNC    → Import CDRs and subscription data
2. CALCULATE → Run totals calculation
3. BACKUP   → Save to historical table
4. SAVE     → Update status

Providers: - KPN SP16, EEN, GRIP - Vodafone - T-Mobile Calvi - Routit Mobile - Yielder/Odido

See: Provider Workflows →

3. Totals Calculation¶

CDRs in database
  ↓
DispatchTotalsHandler (router)
  ↓
CalculateTotalsHandler
  ↓
Query CDRs for period
  ↓
Apply rate plans
  ↓
Calculate costs
  ↓
Update totals table
  ↓
Generate billing insights

See: CDR Processing →

Critical Components¶

Single Points of Failure

If these components break, automation stops:

1. sync:manager Cron Job¶

Runs: Every 5 minutes
Impact: ALL automated syncs stop
Monitors: Check cron execution logs

2. MessageConsumedHandler¶

Purpose: Enables ALL command chaining
Impact: Workflow chains break
Location: src/MessageBus/MessageConsumedHandler.php

3. SyncProfileHandler¶

Purpose: Routes to all provider sync handlers
Impact: ALL provider syncs stop
Location: src/MessageBus/AsynchronousHandler/SyncProfileHandler.php:153

See: Single Points of Failure →

What Gets Automated¶

Provider Data Sync¶

CDR imports (calls, SMS, data) Subscription updates Device information Invoice data Cost information

Billing Calculations¶

Usage totals by subscription Cost calculations with rate plans Billing insights and anomalies Partner-level aggregations Historical backups

Reports & Exports¶

Customer usage reports Excel exports PDF invoice generation Billing insight reports

Administrative¶

Status updates Error notifications Sync orchestration Queue processing

Key Features¶

Asynchronous Processing¶

Commands are dispatched to MessageBus and processed asynchronously, preventing UI blocking and enabling parallel execution.

Command Chaining¶

Commands can attach chains of follow-up commands that execute automatically after completion.

$command = new SyncCommand(...);
$command->withChain([
    new CalculateTotalsCommand(...),
    new BackupCommand(...)
]);

Event-Driven Architecture¶

MessageConsumedHandler listens for completed commands and automatically triggers chained commands.

Multi-Provider Support¶

Single system handles 6 different provider APIs with unified architecture.

Robust Error Handling¶

Automatic retries on transient failures
Status tracking in database
Email notifications on critical errors
Detailed logging

Getting Started¶

For New Developers¶

Understand the Architecture
Read System Architecture
Understand Key Concepts
Review Master Sync Flow
Explore Components
Browse Console Commands
Understand Message Handlers
Learn Event System
Trace Workflows
Follow Provider Workflows
Understand CDR Processing
Review User Workflows

For Troubleshooting¶

Check Common Issues
Follow Debugging Guide
Search FAQ
Use Command Index to find relevant commands

For Quick Reference¶

Command Index - Find any console command
Handler Index - Lookup MessageBus handlers
Workflow Index - Access workflow documentation
Glossary - Define technical terms

Documentation Status¶

100% Complete & Verified

260 components fully documented
115 console commands cataloged
36 MessageBus handlers documented
10 workflows with visual diagrams
24/24 verification tests passing
Zero failures, zero warnings

Quick Tips¶

Find a Command¶

php bin/console list | grep sync

Debug a Sync¶

php bin/console sync:manager --customer=123 -vvv

Recalculate Totals¶

php bin/console totals:new --customer=123 --cycle=2025-01-01

Check Sync Status¶

SELECT * FROM sync_task
WHERE customer_id = 123
ORDER BY created_at DESC
LIMIT 10;

Next Steps¶

Choose your path:

I'm new to ExpensisI need to debug somethingI need to find somethingI need to understand a workflow

Use Search (press /)
Check Reference Indexes
Browse Glossary

Ready to dive in? Start with the Quick Start Guide →