1.0 Engineering Philosophy
We approach application development not as a process of coding features, but as system design. Every codebase must be simple, readable, and highly maintainable.
1.1 The SOLID Paradigm
We write code compliant with SOLID principles. We prioritize single responsibility classes. We separate business logic from HTTP actions by utilizing dedicated action classes, service layers, and data transfer objects (DTOs). Controllers must remain thin, serving only to route requests, call actions, and return responses.
1.2 Predictable Execution
We avoid side-effects. Database transactions are wrapped in `DB::transaction()` locks to ensure atomicity. Eloquent models are locked down against lazy-loading in development to avoid N+1 database queries.
2.0 Git & Branching Strategy
Our branching rules are simple and strictly enforced. All code commits must undergo peer code review before they reach main branches.
2.1 Branch Management
We use a simplified git-flow protocol. The main branch corresponds directly to production. The staging branch corresponds to the staging environment. Engineers write code in branches prefixed with feature/ or hotfix/.
2.2 Pull Requests & Peer Review
A pull request (PR) requires approvals from at least two senior engineers. We check for type coverage, optimal query counts, logic duplication, and design system alignment.
3.0 Coding Standards
We enforce strict standards to ensure any of our 13 developers can open any of our codebases and immediately understand the code context.
3.1 PSR compliance & Pint
All codebases must conform to PSR-12 formatting rules. We run Laravel Pint in our CI pipeline to automatically format styling issues on commit.
3.2 Strict Type Declarations
Every PHP file must start with declare(strict_types=1);. Method parameters, properties, and returns must be explicitly typed. Docstrings are used only to describe business domain logic, not type hinting.
4.0 Testing & Quality Assurance
We maintain a strict testing protocol. An untested feature is considered broken by default.
4.1 90% Test Coverage
All agency repositories require at least 90% lines-of-code coverage. We write unit tests for isolated domain logic and integration/feature tests for API routes and controllers.
4.2 Pest PHP
Our default testing tool is Pest PHP. It allows us to write expressive, functional assertions that double as system specification documentation.
5.0 Infrastructure & CI/CD
We build code to run on modern, automated cloud infrastructures. We avoid manual server configurations or FTP deployments.
5.1 Deployments & Provisioning
We provision production environments using Laravel Forge or directly using AWS Terraform scripts. Deployments are orchestrated using Laravel Envoyer to guarantee zero-downtime rolling updates.
5.2 Horizontal Auto-scaling
For enterprise workloads, we isolate services: web servers run stateless behind Load Balancers, Redis queues run on dedicated worker nodes, and databases run on replicated RDS configurations.
6.0 Security Protocols
Security is not a feature added at the end; it is baked into every architecture decision.
6.1 Data Compliance
We adhere to HIPAA (health records) and PCI-DSS (payment transactions) controls. Any sensitive user data is encrypted at rest using Laravel's encryption engine and database column locks.
6.2 Strict Threat Mitigation
All endpoints enforce strict rate-limiting. Eloquent bindings are monitored to prevent SQL injection. We utilize static analysis tools (PHPStan) set to level 9 in our pipelines to trace potential safety leaks.
7.0 Engineering Lifecycle & System Design
We enforce a structured pre-coding design phase. No feature is developed without domain separation and logic mapping. This prevents code sprawl and aligns architectural goals.
7.1 Module Discovery
Before writing database models, we group application capabilities into strict **Domain Modules**. Modules are isolated code buckets (e.g., Billing, Subscriptions, TenantManagement).
- Each module owns its database migrations.
- Modules must interact via defined interfaces/contracts, not direct cross-module imports.
- Direct cross-joins between tables of different modules are strictly prohibited.
7.2 Logic Mapping & Visual Flowcharts
For any feature touching financial states, multi-party routing, or external APIs, the developer must design a visual flowchart (Mermaid or Draw.io schema) documenting state transformations and rollback triggers.
Example Architectural Flow: Subscription Checkout Pipeline
Below is an example of our visual logic mapping for a multi-tenant subscription flow. It defines step isolation, API requests, and rollback loops.
2. Unlock database row.
3. Dispatch SubscriptionCreated event (runs async mailer, CRM webhook).
2. Log API payload with failure reasons.
3. Release database lock.
4. Return customized JSON error code.
Laravel Code Translation Structure
To represent this flow in code, the controller calls a single transactional action class:
// app/Http/Controllers/SubscriptionController.php
public function store(CheckoutRequest $request, ProcessCheckoutAction $checkout)
{
$subscription = $checkout->execute(
CheckoutData::fromRequest($request)
);
return SubscriptionResource::make($subscription);
}