This file provides guidance to Claude Code (claude.ai/code) when working with MikoPBX repository.
MikoPBX is an open-source PBX (Private Branch Exchange) system for small businesses built on Asterisk. It provides a web-based GUI for managing phone system functionality using PHP 8.3 and Phalcon Framework 5.8.
- Main repository: https://github.com/mikopbx/Core
- Development documentation: https://github.com/mikopbx/DevelopementDocs
- Module template: https://github.com/mikopbx/ModuleTemplate
📖 PHP — use the php-style skill (PSR-1/4/12, PHP 8.3 features).
📖 JavaScript — use the js-style skill (ES6+, Fomantic-UI, jQuery patterns).
- Use
use Phalcon\Di\Di;instead ofuse Phalcon\Di;in imports.
src/
├── AdminCabinet/ # Web administration interface (MVC) → CLAUDE.md
├── Common/
│ ├── Providers/ # Service providers for DI container → CLAUDE.md
│ └── Models/ # Database models → CLAUDE.md
├── Core/
│ ├── Asterisk/ # Asterisk config generation → CLAUDE.md
│ ├── System/ # Network, IPv6, containers, boot → CLAUDE.md
│ │ └── CloudProvisioning/ # Cloud/NoCloud provisioning → CLAUDE.md
│ └── Workers/ # Background job processors → CLAUDE.md
├── Modules/ # Module system base classes → CLAUDE.md
├── PBXCoreREST/ # REST API implementation → CLAUDE.md
└── Service/ # Service layer components
tests/ # AdminCabinet (PHPUnit+Selenium), api (pytest),
# Calls (bash/PHP), pycalltests (PJSUA2), PBXCoreREST
sites/ # Web assets and entry points
resources/ # Static resources (DB, sounds, rootfs)
Each subdirectory CLAUDE.md is auto-loaded when you read files in that subtree —
keep deep detail there, not here.
- Database:
/cf/conf/mikopbx.db - System messages:
/storage/usbdisk1/mikopbx/log/system/messages - PHP errors:
/storage/usbdisk1/mikopbx/log/php/error.log - Nginx errors:
/storage/usbdisk1/mikopbx/log/nginx/error.log - Asterisk logs:
/storage/usbdisk1/mikopbx/log/asterisk/ - Fail2ban logs:
/storage/usbdisk1/mikopbx/log/fail2ban/fail2ban.log
Use the container-inspector skill for container IPs/ports and restarts
(Docker + LXC), and the log-analyzer skill to diagnose log/worker issues.
The /offload partition (rootfs) is mounted read-only. To deploy files:
busybox mount -o remount,rw /offload
# copy files to /offload/rootfs/usr/www/...
busybox mount -o remount,ro /offloadImportant: Use busybox mount, not bare mount — the system mount may fail on T2/Linux.
Mount point is /offload (not /offload/rootfs).
When packaging files on macOS for /offload/rootfs/usr/www, use COPYFILE_DISABLE=1 tar --no-xattrs ... to suppress AppleDouble (._*) artefacts. Otherwise every directory on the host gets a parallel ._* file (Forms/, Configs/, Messages/, …).
After editing any src/Common/Messages/*.php, the cached globalTranslateArray at /var/tmp/www_cache/js/localization-<lang>-<hash>.min.js MUST be deleted on the target host. AssetProvider::makeLocalizationAssets() regenerates it only if the file is missing — the version hash does NOT recompute from translation content changes.
Tests are synced host↔container: Host src/Core/tests → Container /offload/rootfs/usr/www/tests.
- Call Flow Integration (
tests/Calls): bash/PHP on separate Asterisk (port 5062), CDR comparison,ffprobefor recording duration. Seetests/Calls/README.md. - SIP Call Flow (
tests/pycalltests): runs inside container via PJSUA2 SWIG bindings, direct FS access for voicemail/recordings/audio. Seetests/pycalltests/README.md.
// For CLI PHP scripts and tests
require_once 'Globals.php'; // !!!IMPORTANT!!! NO NEED ANY PATH- Include new JS/CSS through
AssetProvider. - Use the
babel-compilerskill to transpile ES6+ → ES5, andjs-styleto validate.
Use the translations skill (29 languages, Russian-first): add/translate/check/remove keys.
- Dependency Injection — Phalcon DI container, providers in
src/Common/Providers/andsrc/Core/Providers/. - Worker System — base
WorkerBase; Beanstalkd (CDR/Events) + Redis (API) queues; file-based JSON-task workers;WorkerSafeScriptsCoresupervisor; crash watchdog auto-disables module workers crashing 100+ times in 30 min (DISABLED_BY_CRASH_LOOP). →src/Core/Workers/CLAUDE.md - Module System — base
PbxExtensionBase, deployed to/var/www/mikopbx/. Disable reasons:DISABLED_BY_USER,DISABLED_BY_EXCEPTION,DISABLED_BY_LICENSE,DISABLED_BY_CRASH_LOOP. →src/Modules/CLAUDE.md - Asterisk Configuration — generators in
src/Core/Asterisk/Configs/, stage-based (pre → generate → post), dual-stack IPv4/IPv6. →src/Core/Asterisk/CLAUDE.md - Event System — Nginx nchan pub/sub;
EventBusProviderpublishes via REST API; WebSocket for browser updates. - Database — SQLite for main DB and (separate) CDR DB. Models in
src/Common/Models/. →src/Common/Models/CLAUDE.md - REST API — queued architecture: controllers enqueue to Redis for async processing; backpressure protection (fast-fail HTTP 503, stale-request drop). →
src/PBXCoreREST/CLAUDE.md - Admin Cabinet — Phalcon MVC + Volt templates, Fomantic/Semantic UI. →
src/AdminCabinet/CLAUDE.md - Network / System — dual-stack IP handling (
IpAddressHelper),Networkconfig manager, DHCP clients, container detection, boot. →src/Core/System/CLAUDE.md - Cloud Provisioning — unified ENV/IMDS/NoCloud provisioning with direct SQLite (early boot, no Redis). →
src/Core/System/CloudProvisioning/CLAUDE.md
- MVC (AdminCabinet), Provider (DI registration), Worker (async queues), Hook System (modules hook into processes), Stage (multi-stage config generation), DHCP Callback (event-driven network config), Smart Console (test console accessibility before redirect).
WorkerBase,PbxExtensionBase,ConfigInterface,AsteriskConfInterface,PBXCoreRESTSystem— container/capability detection (isDocker/isLxc/isContainer/canManageNetwork/canManageFirewall). Seesrc/Core/System/CLAUDE.md.IpAddressHelper— dual-stack IPv4/IPv6 validation & CIDR utilities.Network,Udhcpc(IPv4),Udhcpc6(IPv6),DnsConf,IptablesConf— seesrc/Core/System/CLAUDE.md.CloudProvider,ProvisioningConfig,NoCloud— seesrc/Core/System/CloudProvisioning/CLAUDE.md.
asterisk (PBX engine), beanstalkd (queue), redis (cache/IPC/API queue), php-fpm, nginx, fail2ban.
MikoPBX runs as a single container (Docker app-container or LXC system-container)
bundling PHP 8.3, SQLite, Redis, Beanstalkd, Asterisk, Nginx. Container detection,
the Docker-vs-LXC capability matrix, IPv6 modes, DHCP callbacks and the boot/console
system are documented in src/Core/System/CLAUDE.md.
- Admin UI · REST API · Workers · Modules
- Asterisk · Models · Providers
- System/Network/Boot · Cloud Provisioning
- System Diagnostic · Browser Tests
Skills and agents are surfaced automatically each session — just describe the task in natural language (EN/RU) and the matching one is selected. Notable groups:
- API/DB testing:
api-client,auth-token-manager,openapi-analyzer,endpoint-validator,api-test-generator,sqlite-inspector,restapi-translations - Infra/diagnostics:
container-inspector,log-analyzer,asterisk-validator,asterisk-tester,teamcity-monitor,browserstack-tester,sentry-analyzer - Code quality:
php-style,js-style,code-search(ast-grep),babel-compiler,translations,commit-messages - Agents (
.claude/agents/):test-fix-loop-agent,js-optimizer-mikopbx,php-refactoring-specialist,security-audit-analyzer,pbx-translation-expert,rest-api-docker-tester,mikopbx-web-tester,lxc-provisioning-tester,service-documentation
- Security/UI: XSS Protection, DataTable Guidelines, Tooltip Guidelines
- External: Phalcon, Fomantic-UI, PHP, Asterisk
- Use the
test-fix-loop-agentto execute API tests with automated remediation. - Do not use mock services for anything ever.
- Do not move on to the next test until the current test is complete.
- If the test fails, consider checking if the test is structured correctly before deciding we need to refactor the codebase.
- Tests to be verbose so we can use them for debugging.
- Criticism is welcome. Please tell me when I am wrong or mistaken, or even when you think I might be wrong or mistaken.
- Please tell me if there is a better approach than the one I am taking.
- Please tell me if there is a relevant standard or convention that I appear to be unaware of.
- Be skeptical.
- Be concise.
- Short summaries are OK, but don't give an extended breakdown unless we are working through the details of a plan.
- Do not flatter, and do not give compliments unless I am specifically asking for your judgement.
- Occasional pleasantries are fine.
- Feel free to ask many questions. If you are in doubt of my intent, don't guess. Ask.
- NO PARTIAL IMPLEMENTATION
- NO SIMPLIFICATION : no "//This is simplified stuff for now, complete implementation would blablabla"
- NO CODE DUPLICATION : check existing codebase to reuse functions and constants Read files before writing new functions. Use common sense function name to find them easily.
- NO DEAD CODE : either use or delete from codebase completely
- IMPLEMENT TEST FOR EVERY FUNCTIONS
- NO CHEATER TESTS : test must be accurate, reflect real usage and be designed to reveal flaws. No useless tests! Design tests to be verbose so we can use them for debuging.
- NO INCONSISTENT NAMING - read existing codebase naming patterns.
- NO OVER-ENGINEERING - Don't add unnecessary abstractions, factory patterns, or middleware when simple functions would work. Don't think "enterprise" when you need "working"
- NO MIXED CONCERNS - Don't put validation logic inside API handlers, database queries inside UI components, etc. instead of proper separation
- NO RESOURCE LEAKS - Don't forget to close database connections, clear timeouts, remove event listeners, or clean up file handles
- use Phalcon\Di\Di; instead of use Phalcon\Di; in imports.