Skip to content

Quick Start Guide

Find What You Need Fast

Find a specific command

Console Commands: 

# List all commands
php bin/console list

# Search documentation
grep "command-name" docs/components/console-commands.md

Browse by category:

Understand how sync works

  1. Read: Master Sync Workflow
  2. See: System Architecture
  3. Trace: SyncProfileHandler code

Debug a failing sync

  1. Check sync_task table for status
  2. Review Common Issues
  3. Trace workflow in Workflows section
  4. Check handler logic

Add new automation

  1. Review Extension Points
  2. Follow existing patterns
  3. Add command + handler
  4. Update this documentation
  5. Run verification tests

How often does sync run?

Every 5 minutes via sync:manager cron job

*/5 * * * * php bin/console sync:manager

See: Cron Jobs

What triggers totals calculation?

Multiple sources:

  • After every provider sync
  • Manual trigger from web UI
  • Console command: php bin/console totals:calculate
  • API endpoint calls

See: Totals Workflow

How do command chains work?

Commands can attach chains using withChain():

$command = new DispatchTotalsCommand($customerId, $date);
$command->withChain([
    new CalculateTotalsCommand($customerId, $date),
    new DispatchTotalsBackupCommand($customerId, $date)
]);
$this->commandBus->dispatch($command);

MessageConsumedHandler automatically executes the chain.

See: Chain Architecture

Where are CDRs stored?

Table: call_detail_record (partitioned by month)

Import process:

  1. Provider scraper downloads files
  2. Import command parses CSV/XML
  3. CDRs inserted into database
  4. Totals calculated from CDRs

See: CDR Workflow

Most Used Commands

Command Purpose Frequency
sync:manager Master orchestrator Every 5 min
odido:handle:queue Process Odido queue Every minute
totals:calculate Calculate totals On demand
routit:cdr:sync Sync Routit CDRs Scheduled

Critical Files

File Purpose
MessageConsumedHandler.php Chain executor (critical!)
SyncProfileHandler.php Master router
SyncManagementService.php Sync orchestration
messenger.yaml Command routing config
services.yaml Handler bindings

Database Tables

Table Purpose
sync_task Sync execution tracking
sync_profile Sync configuration
call_detail_record CDR storage
totals Billing totals
*_import_queue Import job queues

Key Directories

src/
├── Command/              # 115 console commands
├── Controller/           # Web controllers
├── MessageBus/
│   ├── Command/          # 40 MessageBus commands
│   └── AsynchronousHandler/  # 36 handlers
└── Service/              # Business logic

Common Tasks

1. Running a Sync Manually

# Sync specific provider
php bin/console kpn:sp16:scrape --customer=123

# Sync all active profiles
php bin/console sync:manager

# Force sync (bypass checks)
php bin/console kpn:sp16:scrape --customer=123 --force

2. Calculating Totals

# Calculate for specific customer/period
php bin/console totals:calculate 123 2025-01-01

# Recalculate all Calvi partners
php bin/console calculate-totals:calvi-partners 2025-01-01

3. Checking Sync Status

-- Check recent sync tasks
SELECT * FROM sync_task 
WHERE created_at > NOW() - INTERVAL 1 HOUR
ORDER BY created_at DESC;

-- Check failed syncs
SELECT * FROM sync_task
WHERE status = 'failed'
ORDER BY created_at DESC
LIMIT 10;

4. Viewing Logs

# Follow application logs
tail -f var/log/prod.log

# Filter for sync errors
grep "Sync failed" var/log/prod.log

# Check Messenger worker logs
tail -f var/log/messenger.log

Learning Path

Beginner (Day 1)

  1. Read: Overview
  2. Read: Key Concepts
  3. Review: System Architecture
  4. Explore: Command Index

Intermediate (Week 1)

  1. Study: Master Sync Workflow
  2. Trace: Provider Workflows
  3. Understand: Command Chains
  4. Review: Dependencies

Advanced (Month 1)

  1. Deep dive: All Workflows
  2. Master: Dispatch Points
  3. Debug: Common Issues
  4. Extend: Add new automation following patterns

Search Tips

The search bar (press / to focus) supports:

  • Command names: sync:manager
  • Class names: MessageConsumedHandler
  • Concepts: command chaining
  • Error messages: failed sync
  • Technical terms: dispatch, handler, cron

Pro Tips

Use the Command Palette

Press Ctrl+K (or Cmd+K on Mac) to open the command palette for quick navigation

Bookmark Frequently Used Pages

Check Git History

When documentation is unclear, check the actual code: 

git log -p -- src/MessageBus/MessageConsumedHandler.php

Next Steps: