# B2B Workspace Platform Modernization, WebSocket Hardening & AI-Ready Handover Canonical URL: https://aquarel.io/case-studies/b2b-workspace-php-angular-websocket-modernization Attribution Status: anonymized (Multi-Tier B2B Workspace SaaS (Anonymized — Ready for Named Toggle)) Stack: PHP 8.3 & Yii 2, Angular 22 SPA, Ratchet WebSockets, Multi-Tier AGENTS.md, Zero-Downtime CI/CD > How Aquarel stabilized and modernized a multi-tier B2B workspace platform without production downtime—upgrading the backend to PHP 8.3 and the SPA to Angular 22, resolving multi-client Ratchet WebSocket broadcast crashes and deployment script failures, and authoring multi-tier AGENTS.md guardrails for safe AI-assisted engineering. ## Key Production Outcomes & Metrics - **PHP 8.3 + Angular 22**: Full-stack runtime modernization shipped with zero downtime - **3 Tiers**: Backend, REST API, and SPA locked behind AGENTS.md guardrails - **0 Crashes**: Post-fix Ratchet WebSocket multi-client broadcast stability ## 4-Quadrant Engineering Diagnostic Breakdown ### 01 / Business Symptom & Risk Legacy server-rendered modules, runtime incompatibilities blocking PHP 8.3 upgrades, WebSocket broadcast crashes under concurrent multi-workspace sessions, and fragile deployment scripts risking partial production outages. ### 02 / Root Technical Diagnosis Uncaught payload serialization failures in the Ratchet WebSocket loop, unguarded shell commands in CI/CD scripts lacking set -e and process isolation, and undocumented architectural boundaries across backend/API/frontend tiers. ### 03 / Surgical Engineering Fix Migrated legacy modules (Strategers, Settings, Constructors) to clean REST API + Angular 22 SPA modules, hardened WebSocket connection state handling, isolated supervisorctl workers, and wrote tier-specific AGENTS.md specifications. ### 04 / Measurable Outcome Zero-downtime production cutover to PHP 8.3 & Angular 22, stable real-time multi-client synchronization, deterministic deployments, and an AI-safe repository ready for rapid ongoing feature delivery. ## Engineering Deep Dive ## Modernizing a Multi-Tier B2B Workspace Platform & Installing `AGENTS.md` Guardrails Complex B2B platforms rarely live in a single framework. On this engagement, we upgraded a live multi-tier workspace and process-management platform across **PHP 8.3 / Yii 2**, **Ratchet WebSockets**, and **Angular 22**, eliminated real-time broadcast crashes, hardened deployment automation, and delivered a comprehensive **Vibe-Safe Handover** via tier-specific `AGENTS.md` specifications. ### 1. Zero-Downtime PHP 8.3 & Angular 22 Strangler-Fig Migration The platform combined legacy server-rendered Yii 2 views with a growing single-page application, creating friction whenever new workspace capabilities were introduced: - **Runtime Upgrade to PHP 8.3 & Angular 22:** Audited and resolved strict typing, deprecation, and dependency incompatibilities across both the Yii 2 backend and the Angular SPA so the entire stack could run on modern, supported runtimes. - **Module-by-Module Extraction (`Strategers`, `Settings`, `Constructors`):** Migrated critical legacy workspace modules (`Strategers`, `Settings`, and `Constructors`) out of coupled server-rendered templates into clean, versioned REST API controllers consumed by modular Angular 22 components. ### 2. Ratchet WebSocket Hardening & Deterministic `supervisorctl` Deployments Real-time collaboration across B2B workspaces depended on a long-running Ratchet WebSocket server that periodically crashed or dropped broadcasts during multi-client sessions and deployments: - **Fault-Tolerant WebSocket Broadcast Loop:** Isolated connection state management and guarded payload serialization inside the Ratchet event loop so a malformed client frame or disconnected socket could never terminate the broadcast daemon for other active workspaces. - **Fail-Fast Deployment Scripts (`set -e` & `supervisorctl` Isolation):** Re-engineered deployment scripts with strict `set -e` error trapping, atomic asset builds, and clean `supervisorctl` worker lifecycle restarts so broken builds could never partially deploy to production. ### 3. Multi-Tier `AGENTS.md` Vibe-Safe Handover To ensure the engineering team could safely use AI coding assistants (Claude Code, Cursor) across a multi-repository/multi-tier architecture without introducing cross-tier regressions, we authored root and tier-specific `AGENTS.md` contracts documenting frozen authentication filters, REST payload schemas, WebSocket frame contracts, and deployment invariants. ## Related Rescue Services - [saas-scaling-and-refactoring](https://aquarel.io/services/saas-scaling-and-refactoring) - [claude-cursor-replit-rescue](https://aquarel.io/services/claude-cursor-replit-rescue) - [vibe-code-app-rescue](https://aquarel.io/services/vibe-code-app-rescue) ## Frequently Asked Questions ### What did the multi-tier AGENTS.md handover include on this project? We authored explicit repository instruction contracts across the backend, REST API, WebSocket daemon, and Angular SPA tiers so AI coding assistants respect authentication boundaries, strict typing, and deployment scripts. ### How did you migrate legacy server-rendered modules without breaking active customer workspaces? Using the strangler-fig pattern: we extracted clean REST endpoints and Angular SPA feature modules slice by slice, verifying each module in staging before cutting over traffic. ### Why did the deployment and supervisorctl scripts require surgical hardening? Without strict shell fail-fast flags (set -e) and isolated supervisorctl worker restarts, a failed build step or stale WebSocket daemon could leave production in a split-brain state between the PHP 8.3 API and Angular 22 frontend. ## Book a Free 20-Minute Triage Call - [Request Triage or Free 48h Codebase Audit](https://aquarel.io/triage)