ISP/CRM Modernization
Re-engineering a production ISP management platform from a legacy PHP system into a testable, domain-oriented reference architecture
Original system: 2014
Re-engineered: 2026
Category: Enterprise Software / Legacy Modernization / Backend Engineering
Reference implementation: Laravel 12
Database: PostgreSQL
Architecture: Modular Monolith / Domain-Oriented Architecture
Testing: 836 Automated Tests / 7,274 Assertions
Project Overview
In 2014, I developed one of my major software projects for an Internet Service Provider.
The system was not a simple website or administrative dashboard.
It was an operational ISP/CRM platform responsible for managing a significant part of the company's day-to-day business processes, including customers, services, contracts, billing, payments, support, communications and operational workflows.
At the time, the application was built primarily with traditional PHP.
The complete system was remarkably compact:
- approximately 23 MB
- around 104 core PHP files
- individual files containing up to approximately 3,000 lines of code
That architecture was influenced by the technical and operational environment of the time.
The software needed to be deployed quickly, remain lightweight and operate inside an infrastructure where external access was heavily restricted at the network and firewall level.
For 2014, the system was practical.
Twelve years later, however, my definition of a successful software system had changed significantly.
The question was no longer simply:
Does the software work?
The new questions were:
Can its behavior be precisely defined?
Can its business rules be independently verified?
Can financial operations be protected by explicit invariants?
Can authorization decisions be tested rather than assumed?
Can the architecture evolve without silently changing existing behavior?
Can another engineer understand why the system behaves the way it does?
Those questions became the foundation of the 2026 modernization.
The Original 2014 System
The original application followed a development style that was common and practical for many PHP applications of that period.
Responsibilities that would normally be separated in a modern architecture often existed close together.
A single application flow could involve:
- SQL queries
- business rules
- authentication
- authorization
- validation
- HTML rendering
- form processing
- session management
- financial calculations
- customer operations
- service operations
In some cases, several of these concerns existed within the same PHP file.
This reduced abstraction overhead and helped keep the application compact.
It also allowed features to be implemented quickly.
But as the system grew, the same characteristics created long-term architectural limitations.
Large files became responsible for multiple business concerns.
Database operations were closely connected to application behavior.
Business rules were sometimes implicit in execution flow rather than explicitly modeled.
Authorization behavior was distributed across different parts of the system.
Testing individual rules independently was difficult.
The architecture worked, but much of the system's knowledge existed inside the implementation itself.
Why I Revisited the Project
When I returned to the project in 2026, I deliberately avoided treating the modernization as a framework upgrade.
Replacing old PHP syntax with modern PHP would not solve the architectural problem.
Moving existing code into a newer framework without understanding its behavior would simply move technical debt into a newer directory structure.
So I approached the project differently.
The modernization started with:
reverse engineering the behavior of the legacy system.
The objective was to identify:
- business entities
- business rules
- workflows
- state transitions
- authorization requirements
- financial invariants
- side effects
- integrations
- data relationships
- historical behavior
Only after understanding those concepts could the system be reconstructed in a modern architecture.
From Legacy Code to Domain Model
The legacy application contained years of operational knowledge.
That knowledge needed to be extracted from implementation details and converted into explicit domain concepts.
The modernized system therefore separates major business areas such as:
- CRM
- Customer Management
- Customer Contacts
- Contracts
- Service Plans
- Service Lifecycle
- Service Lines
- Service Cases
- Service Case Transitions
- Invoices
- Payments
- Financial Ledger
- Support
- Messaging
- SMS
- Telegram Integration
- Import & Reconciliation
- Authentication
- Authorization
- RBAC
- Audit Logging
- Customer Portal
- Idempotency
- API Contracts
Instead of allowing these concepts to exist implicitly across unrelated files, they are modeled as identifiable parts of the system.
This makes boundaries clearer and allows individual business rules to be tested independently.
Architecture
The 2026 reference implementation is based on Laravel 12 and PostgreSQL.
However, Laravel is not being used merely as a modern replacement for the original PHP application.
The reference implementation has a more important role:
It acts as an executable specification of the system's expected behavior.
This means the implementation does not only contain working features.
It also defines, through code, constraints and automated tests, what the system is allowed and not allowed to do.
The architecture follows a modular, domain-oriented approach.
Instead of organizing the entire system primarily around controllers and database tables, business capabilities are treated as architectural concepts with explicit responsibilities.
The result is a system that is easier to reason about, test and maintain.
The Reference Implementation
One of the most important milestones of the modernization was reaching a frozen Laravel reference state.
"Frozen" in this context means that the implementation has reached a defined behavioral baseline.
The reference contains:
- database schema
- domain rules
- authorization behavior
- API contracts
- validation rules
- expected state transitions
- test scenarios
- reference datasets
- architectural documentation
The purpose is to make system behavior explicit.
Instead of relying on statements such as:
"This is how the old system probably worked."
the project can express:
"This is the behavior that the reference implementation defines and verifies."
That distinction is fundamental to the modernization strategy.
Customer and CRM Domain
Customer management is one of the central domains of the platform.
A customer is not represented merely as a row containing a name and telephone number.
The model supports relationships between concepts such as:
- customers
- contacts
- services
- service lines
- credentials
- contracts
- invoices
- payments
- support cases
- communications
The objective is to prevent unrelated business responsibilities from accumulating inside a single customer record or controller.
Customer identity and customer-related operations therefore become explicit parts of the domain model.
Service Lifecycle
Internet services naturally have a lifecycle.
A service can move through different operational states over time.
These transitions may affect:
- activation
- suspension
- cancellation
- credentials
- billing
- technical provisioning
- customer communication
A major architectural improvement was to make these transitions explicit.
Instead of directly modifying status fields from arbitrary parts of the application, transitions can be modeled as business operations.
This creates an important distinction:
A state describes where an entity currently is.
A transition describes how and why it moved there.
That difference improves auditability and makes invalid transitions easier to prevent.
Financial Architecture
Financial behavior is one of the areas where implicit application logic creates the highest risk.
The modernized architecture therefore treats financial operations as explicit domain behavior.
The system models concepts including:
- invoices
- payments
- financial entries
- reconciliation
- financial state transitions
A particularly important principle is the use of an:
Immutable Financial Ledger
Once a financial event has been committed to the ledger, normal application operations should not silently rewrite its history.
Corrections should be represented through explicit compensating or subsequent operations rather than destructive modification of historical financial records.
This improves:
- traceability
- auditability
- reproducibility
- financial consistency
It also creates strong invariants that can be tested automatically.
Idempotency
Idempotency became another explicit architectural concern.
Consider a payment request.
A client sends the request.
The server processes the payment successfully.
Before the response reaches the client, the network connection fails.
The client retries.
Without idempotency protection, the second request could create another financial transaction.
The modernized system therefore treats retry safety as part of the business contract.
Equivalent requests using the same idempotency context must not create duplicate financial side effects.
This is especially important for:
- payments
- imports
- external integrations
- asynchronous operations
- retryable API requests
Idempotency is therefore tested as behavior rather than documented merely as an implementation recommendation.
Authentication and Authorization
Authentication answers:
Who is the user?
Authorization answers:
What is this user allowed to do?
The modern architecture treats these as separate concerns.
A Role-Based Access Control model was introduced with concepts such as:
- roles
- permissions
- role-permission relationships
- user-role relationships
- user-specific permission overrides
This allows authorization to be expressed explicitly rather than scattered across controllers and views.
The test suite also verifies authorization boundaries.
It is not sufficient that an authorized user can perform an operation.
The system must also demonstrate that an unauthorized user cannot perform it.
Tenant and Customer Data Isolation
Authorization is particularly important when customer-specific data is involved.
An authenticated user should not automatically gain access to unrelated customer information.
The architecture therefore treats object-level authorization and data isolation as explicit security requirements.
Tests verify scenarios where users attempt to access resources outside their permitted scope.
This helps prevent one of the most dangerous classes of application vulnerabilities:
valid authentication combined with invalid resource access.
Audit Logging
Enterprise systems need more than application logs.
They need to answer questions such as:
- Who performed an operation?
- What operation was performed?
- Which entity was affected?
- When did it happen?
- What was the result?
The modernized platform therefore includes explicit audit behavior.
At the same time, auditability must not become a mechanism for leaking sensitive information.
The audit system is designed so that security-sensitive values do not become permanently stored merely because an operation was logged.
This behavior is also covered by automated tests.
Import and Reconciliation
Legacy enterprise systems frequently exchange information with external systems through files, imports or periodic synchronization processes.
Imports create several risks:
- duplicate records
- partially processed batches
- inconsistent retries
- invalid relationships
- conflicting data
The modern architecture therefore treats import and reconciliation as defined workflows rather than arbitrary database writes.
Repeated processing must not silently create duplicated business state.
Validation and idempotency principles are applied where appropriate to make import behavior predictable and reproducible.
Messaging and External Communication
The original platform also interacted with external communication channels.
The modern domain model therefore includes communication capabilities such as:
- SMS
- Telegram
- internal messaging
These integrations are treated as external boundaries rather than allowing provider-specific behavior to spread throughout unrelated business logic.
This separation makes communication workflows easier to replace, test and reason about.
API-First Behavioral Contracts
The reference implementation exposes defined API behavior.
An API is not treated merely as a collection of routes.
Each operation has a contract describing aspects such as:
- request structure
- validation
- authentication
- authorization
- response structure
- failure behavior
- side effects
The project includes an OpenAPI specification so that important parts of the external interface can be described in a machine-readable format.
This reduces ambiguity between implementation and documentation.
Automated Testing
One of the largest differences between the 2014 system and the 2026 reference implementation is the role of automated verification.
Current reference status:
836 Automated Tests — PASS
Within those tests:
7,274 Assertions — PASS
These numbers represent two different concepts.
A test represents a scenario or unit of expected behavior.
An assertion verifies a specific condition within that scenario.
For example, a test may execute a payment operation.
Inside that scenario, multiple assertions may verify that:
- the response status is correct
- the payment exists
- the amount is correct
- exactly one ledger entry was created
- the invoice state changed correctly
- an audit event was generated
- unrelated records were not modified
The objective is therefore not to maximize the number of assertions.
The objective is to make important system behavior machine-verifiable.
What the Tests Actually Protect
The test suite covers behavior across different architectural layers.
Examples include verifying that:
- unauthorized users cannot execute protected operations
- users cannot access customer data outside their authorization scope
- issued invoices cannot be silently modified
- financial history cannot be destructively rewritten
- duplicate payment requests do not generate duplicate financial effects
- idempotency rules remain effective
- audit logs do not persist sensitive information
- repeated imports do not create unintended duplicates
- invalid state transitions are rejected
- database invariants remain valid
- failed operations do not produce unintended side effects
This is an important distinction.
The tests do not merely ask:
"Does this endpoint return HTTP 200?"
They ask:
"Did the complete business operation behave exactly as expected, including what must not happen?"
Negative behavior is part of the specification.
Side-Effect Control
One of the most important lessons in enterprise software is that a failed operation can be more dangerous than an operation that simply throws an error.
Imagine an operation that:
- creates a payment,
- updates an invoice,
- writes a ledger entry,
- sends an event,
- then fails.
If the transaction boundaries are incorrect, the application may report failure while leaving part of the operation committed.
The modern reference therefore tests not only successful outcomes but also failure behavior.
A rejected or failed operation must not leave the system in an unintended intermediate state.
This principle is critical for financial and operational consistency.
Database Architecture
The reference implementation uses PostgreSQL.
The database schema is not treated as passive storage.
It participates in protecting important invariants through:
- relational constraints
- foreign keys
- uniqueness rules
- appropriate data types
- explicit relationships
Application-level validation and database-level integrity complement each other.
Validation provides meaningful application behavior.
Database constraints provide a final structural boundary against invalid persistent state.
Golden Dataset
A defined Golden Dataset is part of the reference architecture.
The purpose of a golden dataset is to provide deterministic input data with known expected behavior.
Instead of validating complex system behavior against arbitrary development records, the project can execute scenarios against a controlled reference dataset.
This improves:
- reproducibility
- regression detection
- debugging
- behavioral comparison
If the same inputs unexpectedly produce different outputs after a change, the difference can be investigated systematically.
Golden Master Testing
The project also uses the concept of Golden Master Tests.
Golden master testing is particularly valuable when modernizing legacy systems.
A legacy system may contain behavior that is difficult to describe completely from documentation alone.
By capturing known expected outputs and comparing future execution against them, behavior can be protected during architectural changes.
This does not mean that every historical behavior must be preserved forever.
It means behavioral changes become deliberate.
A difference should exist because an engineering decision changed the specification — not because a refactoring silently altered behavior.
Architecture Package
The project contains an architecture package describing the system beyond implementation details.
The goal is to preserve engineering knowledge about:
- domain boundaries
- important invariants
- system responsibilities
- data relationships
- API behavior
- security expectations
- integration boundaries
Code explains how something currently works.
Architecture documentation should also explain why important boundaries and constraints exist.
That distinction becomes increasingly important as systems grow.
Security as System Behavior
Security is not treated as one middleware layer placed in front of the application.
It exists across multiple levels:
Authentication
Who is making the request?
Authorization
Is the actor allowed to perform this operation?
Object-level access
Is the actor allowed to access this specific resource?
Data integrity
Can invalid state be persisted?
Financial integrity
Can financial history be silently changed?
Audit safety
Can sensitive information leak into permanent logs?
Replay protection
Can retrying a request create duplicate effects?
These properties are part of the architecture and, where practical, part of the automated test suite.
Legacy Modernization Philosophy
One of the most important decisions in this project was not to equate modernization with rewriting.
A rewrite that ignores the accumulated business behavior of the previous system can easily produce cleaner code and a worse product.
Legacy systems often contain years of implicit knowledge:
- exceptions
- operational workflows
- business constraints
- edge cases
- historical assumptions
The modernization process therefore follows a different sequence:
Observe → Understand → Model → Specify → Implement → Verify
rather than:
Delete → Rewrite
This approach significantly reduces the risk of losing important business behavior during modernization.
2014 vs. 2026
The evolution of the project can be summarized clearly.
2014
The primary engineering objective was:
Build a compact operational system that solves the company's immediate business requirements.
The architecture optimized strongly for practical delivery and a small deployment footprint.
2026
The engineering objective became:
Build an explicit behavioral reference in which domain rules, security boundaries, financial invariants, APIs and expected side effects can be independently verified.
The difference is therefore much larger than:
Old PHP → Laravel 12
The real transformation is:
Implicit behavior → Explicit domain rules
Large procedural flows → Defined responsibilities
Database operations → Protected invariants
Manual confidence → Automated verification
Scattered authorization → Explicit RBAC
Mutable financial history → Immutable ledger principles
Retry uncertainty → Idempotent operations
Implementation knowledge → Executable specification
Key Metrics
| Metric | Value |
|---|---|
| Original implementation | 2014 |
| Re-engineered reference | 2026 |
| Original application size | ~23 MB |
| Legacy core PHP files | ~104 |
| Largest legacy files | Up to ~3,000 lines |
| Reference framework | Laravel 12 |
| Reference database | PostgreSQL |
| Automated tests | 836 PASS |
| Assertions | 7,274 PASS |
| API specification | OpenAPI |
| Architecture approach | Modular / Domain-Oriented |
Technical Highlights
- Legacy system reverse engineering
- Domain decomposition
- Modular monolith architecture
- Laravel 12 reference implementation
- PostgreSQL relational model
- Explicit service lifecycle
- Contract and billing domains
- Invoice and payment modeling
- Immutable financial ledger principles
- Idempotent operations
- Role-Based Access Control
- User-specific permission overrides
- Object-level authorization
- Audit logging
- Sensitive-data protection
- Import and reconciliation workflows
- SMS and Telegram integration boundaries
- API contracts
- OpenAPI specification
- Golden Dataset
- Golden Master Tests
- Automated regression testing
- Database invariant validation
- Side-effect verification
- Architecture documentation
Engineering Challenges
The difficult part of this modernization was not converting PHP syntax.
The difficult part was recovering the meaning behind twelve years of legacy behavior.
A line of old code may look unnecessary until the historical workflow that required it is understood.
A database field may look redundant until another process depending on it is discovered.
An unusual conditional branch may represent an important business exception rather than poor programming.
For this reason, modernization required separating three questions:
- What does the legacy system currently do?
- Why does that behavior exist?
- What should the modern specification define?
Only after answering those questions can behavior be safely preserved, corrected or intentionally removed.
That is why I consider this project an exercise in software engineering rather than simply framework migration.
What Changed in My Engineering Approach
The project also provides a useful comparison between two stages of my own development as a software engineer.
In 2014, success was primarily measured by whether the application solved the operational problem reliably enough to be used.
That remains necessary.
But it is no longer sufficient.
Today I also expect important behavior to be:
- explicit
- isolated
- testable
- reproducible
- documented
- observable
- secure
- maintainable
A system should not depend entirely on the original developer remembering why a particular condition exists.
Important knowledge should be represented in architecture, domain rules, contracts and tests.
That is perhaps the biggest difference between the two versions of this project.
Result
The result of the modernization is not simply a cleaner version of a 2014 PHP application.
It is a behavioral reference for a complex ISP/CRM domain.
The Laravel 12 implementation defines the expected behavior of the platform through:
- executable business rules
- relational constraints
- authorization policies
- API contracts
- deterministic reference data
- automated tests
- architectural documentation
With 836 passing automated tests and 7,274 passing assertions, critical behavior is no longer dependent solely on manual testing or undocumented assumptions.
The system's rules can be executed.
Its invariants can be challenged.
Its security boundaries can be tested.
Its financial behavior can be verified.
And architectural changes can be evaluated against a known behavioral baseline.
That is the fundamental difference between the project I built in 2014 and the system I re-engineered in 2026.
From Working Software to Verifiable Software
The original system proved that the business processes could be automated.
The modern reference goes further.
It defines what those processes mean, which transitions are valid, who may execute them, which side effects are permitted, and which invariants must always remain true.
2014 → 2026
From a compact legacy ISP/CRM application to an explicit, testable and verifiable software architecture.
