Project Overview
Ladepeh is an enterprise financial management and invoicing platform designed to handle cross-border commerce, sales cycles, and real-time ledger accounting. Built as a confidential internal ERP system, it supports operations transacting across multiple regional currencies: Turkish Lira (TRY), UAE Dirham (AED), and Iranian Rial (IRR). As a full-stack software engineer on the platform, I architected the core domain services, ledger models, and event pipelines in Laravel, while building the responsive multi-step financial dashboard with Next.js and Zustand.
The Challenge: Multi-Currency Accounting & Consolidated Profit Analysis
Financial software demands absolute precision and deterministic accounting rules. The platform faced specific complex computational challenges:
- Multi-currency ledger segregation: Managing international supplier invoices, freight fees, and customer disbursements across three distinct currencies (TRY, AED, and IRR) with volatile exchange rates. The system had to track balances in each native currency while maintaining an auditable historical conversion trail.
- Real-time profit & loss calculations: Financial controllers needed instant visibility into both currency-specific gross profits and unified, consolidated P&L reports across all accounts simultaneously, without locking up database tables or triggering slow report generations.
- Complex invoicing lifecycles: Managing dynamic proforma quotes, conversions to final commercial invoices, multi-part payments, customer advance deposits, credit limits, and debtor/creditor aging.
Backend Architecture: Laravel DDD & Event-Driven Architecture (EDA)
To keep financial business rules isolated from database storage and framework glue, we implemented Domain-Driven Design (DDD) backed by an Event-Driven Architecture (EDA):
- Domain-Driven bounded contexts: Partitioned the application into decoupled domains (such as Invoicing, Ledger, CurrencyExchange, AccountsPayable, and Reporting). Core business logic is contained in pure Domain Services and Entities, keeping Eloquent models focused on persistence.
- Value Objects for financial safety: Implemented immutable Value Objects like
Money and Currency. Methods such as $money->add($otherMoney) strictly enforce currency matching at the type level, preventing cross-currency addition bugs before code can execute.
- Asynchronous Event-Driven pipelines: State mutations emit domain events (such as
InvoiceFinalized, PaymentRecorded, or LedgerEntryCreated). Decoupled event listeners and queued background jobs handle double-entry journal postings, balance recalculations, automated PDF invoice rendering, and audit log entries without stalling the synchronous HTTP response.
Frontend Engineering: Next.js, Zustand & Adaptive Mobile UI
Financial operations require fast data entry, instant calculations, and usability across desktop and mobile devices:
- Hook-centric state management with Zustand: Financial wizards (including multi-line invoice builders with real-time tax, discount, line-item recalculations, and multi-currency conversions) demand predictable local state. Zustand provided a lightweight, hook-centric store with granular selector subscriptions, eliminating boilerplate and avoiding cascading re-renders across long financial item lists.
- Customized Shadcn/ui & Tailwind design system: Built high-density financial data tables, modal dialogs, date pickers, and searchable selector components customized from Shadcn/ui primitives.
- Dedicated mobile-first responsiveness: Recognizing that executive stakeholders and warehouse staff regularly review invoices and record incoming payments on mobile devices, we built adaptive mobile layouts with optimized touch targets, swipeable ledger rows, and streamlined mobile navigation.
Data Integrity, Concurrency & Precision Math
In financial computing, precision and concurrency safety are non-negotiable:
- Zero-float mathematical accuracy: Prevented IEEE 754 floating-point rounding errors by storing all financial values in high-precision
DECIMAL(18, 4) columns in MySQL and processing arithmetic operations using PHP's BCMath extension with exact arbitrary-precision scaling.
- ACID compliance & database locks: Every ledger entry follows strict double-entry bookkeeping principles. Multi-step invoice payments and balance reconciliations run within isolated
DB::transaction closures with pessimistic row-level locking (lockForUpdate) to guarantee zero account discrepancies during concurrent transactions.
- Immutable audit logs: Financial records, once finalized, cannot be mutated in place; any adjustments require compensating double-entry credit/debit records, providing an immutable audit trail for accounting oversight.
Key Engineering Outcomes
- Multi-currency accuracy: Implemented seamless, zero-discrepancy ledger balancing across TRY, AED, and IRR with automatic historical conversion tracking.
- High-throughput DDD architecture: Decoupled domain models and event-driven queues eliminated blocking operations on complex financial transactions.
- Lightweight, snappy frontend: Zustand state slices delivered instant mathematical reactivity for complex invoicing wizards on both desktop and mobile.
- Enterprise-grade auditability: Immutable journal entries and pessimistic locking ensured 100% data integrity across all account balances.
