Luis
Gonzalez

What It Is

Nexus is a personal SaaS project — an Order Management System built weekend by weekend with a deliberate architectural thesis: that a Django project can scale without becoming a monolith trap. It targets Latin American SMBs that need electronic invoicing (SUNAT), multi-warehouse inventory, and customer traceability in one platform.

The goal is eventually a multi-tenant SaaS where each business (tenant) operates in full data isolation — its own orders, products, clients, and financial reports — on a shared infrastructure. A CRM layer for customer follow-up and sales opportunity tracking is planned for future versions.

Current status: core OMS fully functional, invoicing pipeline wired, 220+ tests passing. Not production-deployed yet — this is active development, not a finished product.

The Architectural Thesis

Most Django projects accumulate logic in models and views until they can't be tested without a running database. Nexus is built against that tendency from the start: Clean Architecture with a hard src/domain/, src/application/, src/infrastructure/, src/interfaces/ boundary structure.

Domain services hold business logic. Models are persistence schemas. Views are thin adapters. The payoff: the 220+ test suite runs deterministically without HTTP calls, mocking only at the infrastructure boundary.

Some parts of the domain are still coupled to Django ORM — an honest tradeoff accepted during active development. The architecture exists as a constraint that makes the coupling visible and removable, not as a description of a finished state.

The Problem

Clínica Santa Isabel's internal payroll system (IsisPlan) handled standard payroll processes but had no module for employee profit-sharing (utilidades). The calculation was done entirely by hand in Excel — manually cross-referencing payroll and liquidation data for ~300 active workers, applying Peruvian labor law rules (D.Leg. 892), and adjusting for fifth-category income tax withholdings.

The process was error-prone and non-reproducible. Workers across the clinic had heterogeneous compensation structures — fixed-salary administrative staff and hourly-rate clinical staff (physicians, nurses, technicians) — each with different calculation bases under law. The hardest edge case: workers who had ceased employment and re-entered within the same fiscal year, requiring pro-rated calculations across two separate employment periods.

The project ran for 3 months from local development to production deployment, replacing the Excel process entirely.

Technical Approach

The pipeline extracted data directly from IsisPlan's PostgreSQL database — using stored procedures to pre-aggregate payroll and liquidation records at the database level before ingestion. This kept complex join and filtering logic in SQL where it performs better, and reserved Python/Pandas for business rule application and edge case handling.

Once loaded into DataFrames, the transformation layer applied profit-sharing rules per worker category, detected cese/reingreso cases via duplicate worker IDs with non-contiguous date ranges, and processed each employment segment independently before aggregating the final entitlement.

A superuser interface allowed the payroll administrator (planillero) to review intermediate values and adjust criteria before committing — specifically for fifth-category tax withholding adjustments that required human judgment. The final results were persisted back to PostgreSQL and surfaced through three outputs: an individual record viewer/modal per worker, a per-worker PDF payment slip, and a master Excel file with all records and calculation variables for audit.

The Problem

Fiberlux operates an ISP with hundreds of active contracts. Any change to a customer's service status — suspension for non-payment, reactivation after payment, cancellation — required the NOC team to manually interact with the OLT (ZENIT ONE) through a web interface.

The existing Odoo module triggered a web scraping robot that simulated browser clicks on the ZENIT ONE interface. Each service change took ~30 seconds, with no actual confirmation that the change was applied in the network. On billing peak days (days 9–10 of each month), processing 94–135 contracts meant ~47 minutes of HTTP worker blockage — causing Odoo timeouts company-wide.

Additional failure modes: the robot had no result verification, silently failed on network changes, and made duplicate calls to a legacy v1 endpoint while the new v2 was active — causing race conditions that corrupted action records.

Architectural Solution

• Direct TL1 API integration via an intermediary service (APIOdoo) — replaced browser scraping with authenticated TL1 commands (CHG-ONU-STAT-PON, LST-ONU-DETAIL) executing in ~7s per service.
• Async dispatch queue — when GPON service count exceeds a configurable threshold (default: 10), set_done() returns in <1s, enqueuing action lines with is_pending_dispatch=True. A dedicated cron dispatches batches of 8 every 2 minutes.
• Polling confirmation cron — separate 5-minute cron calls PollZenitStatus, reading real ADMINSTAT from the OLT port before marking any action as complete. The SSR only closes when all lines are confirmed in the network.
• Multi-equipment discriminator — when ZENIT ONE returns multiple ONU records for the same service ID (migrated or relocated equipment), the system disambiguates by onu_id (last OID segment) — preventing accidental modification of a different customer's port.
• Four-flow state machine — suspension, reactivation, cancellation, and administrative cancellation each have their own valid line state transitions, blocking inappropriate operations silently and correctly.
• Email notification pipeline — async mode sends two emails: one when the dispatch queue empties (services sent to network), one when the SSR closes completely (all confirmed). Applied to both sync and async flows.

The Incident

In December 2025, the call center telephony sync system began generating incomplete data. By January 2026 it had stopped entirely. No alert had fired. No error appeared in the logs. The failure was silent by nature — a public IP change by the infrastructure team, unnotified, had severed the connection to the data source.

Investigation required coordinating with the telephony provider and the NOC team to trace a change that had happened weeks earlier. Once found, the scope became clear: ~50,000 audio recordings and 45 days of CSV reports needed to be recovered from scratch.

The Constraints

The provider's portal had the data — but no bulk download API. Each recording was accessible only via individual button click. The CSV reports were available as master files covering multiple months, requiring segmentation into daily files matching the exact naming format the Odoo sync module expected.

Additional complication: downloaded audio files carried the download date as mtime, not the original call date — and the Odoo sync module used st_mtime to organize files. Uploading them directly would place all 50,000 recordings on a single incorrect date.

The Problem

Fiberlux's custom Odoo module synced telephony data (call recordings, transcripts, quality reports) from Five9's SFTP server into the ERP. The original implementation was fully synchronous — during large data loads, it blocked Odoo's worker processes company-wide, freezing CRM and invoicing operations simultaneously.

Additional issues: data inconsistencies between Five9 and Odoo, growing storage costs from unmanaged file accumulation (~1M files since 2023), and fragile SFTP connectivity with no retry logic.

Architectural Solution

• Decoupled Threading: Migrated SFTP business logic to independent Python threads — achieving zero perceived latency for end users during mass synchronizations.
• Concurrency Control: Indexed boolean flags in PostgreSQL manage thread state and prevent race conditions across concurrent sync workers.
• SQL Optimization: B-Tree indexes on Many2one foreign keys + PostgreSQL views reduced query cost on 40k+ record tables for high-performance reporting.
• Batch Sanitization: Configurable days_to_sanitize with batch processing — auto-purges stale files on schedule, achieving 30% storage reduction.
• Resilient SFTP Client: Re-engineered using Fabric (replacing Paramiko) with hierarchical exception handling and automatic connection retry — handles network instability without operator intervention.
• Memory-Efficient Batch Governor: Configurable batch-size controller terminates remote scanning immediately upon reaching limit, preventing OOM during massive historical migrations.

The Problem

Odoo's standard security model restricts CRM and Sales document ownership to a single Salesperson field. At Fiberlux, multiple executives — Postventa, Fidelización, and others — needed to operate on the same customer account simultaneously.

The result: critical AccessError blocks on every cross-team operation, invoicing bottlenecks, and manual admin intervention required every 2–4 hours.

Architectural Solution

• Dynamic Security Bypass: Re-architected base rules using dot-notation relational paths, enabling safe CRUD for secondary executives without forking Odoo core.
• Context-Aware Approval Dispatch: Dispatcher inside create_level_ids inspects the operating uid and routes approvals to the correct team hierarchy.
• ORM Integrity Fix: Resolved unlink AccessError by bridging: order_id.partner_id.linked_executive_ids.user_id — forcing an implicit JOIN at query time.
• Auto-follower Integration: EVs wired into Odoo's messaging engine as automatic Followers — full lifecycle visibility without manual subscriptions.

The Problem

Fiberlux's invoicing workflow ran entirely inside Odoo — generating a single electronic invoice took ~2 minutes, with no async support. During billing peaks, the process saturated Odoo workers and blocked the entire ERP.

Solution

• 10 parallel async workers — 50 invoices with QR codes in ~35 seconds.
• Async/Sync dual mode — automatic synchronous fallback on API instability.
• Full validation engine — detracciones, exportaciones, IGV, USD/PEN per SUNAT normativa.
• Exponential backoff retry — every state transition recorded atomically for compliance.
• 100% test coverage before production deployment.

The Challenge

Fiberlux operates a critical production ERP on Odoo v13 managing mass invoicing, CRM, telephony integration, and customer contracts — all heavily customized. A v17 upgrade proved infeasible; deprecated APIs, large data volume, and billing continuity requirements drove the decision toward a full Django rewrite.

Phased Extraction Strategy

• Phase 1 — Stabilize v13: Resolved production deadlocks via Odoo worker tuning, memory limits, and PostgreSQL connection pooling. Deployed "Testodoo" environment for safe mass validation.
• Phase 2 — Flat-table Bridge: Migrated first 5 modules using intermediate flat tables — decoupling business logic from Odoo ORM while maintaining data continuity.
• Phase 3 — Extract to Django: Invoicing engine, Five9 sync, and EV governance fully migrated to standalone Django services with clean REST API boundaries.
• Phase 4 — Containerization: Dockerizing v13 production base with environment parity across dev, staging, and production.

The Problem

Critical Odoo and Django workflows exhibited unexplained latency under production load. Without systematic profiling, bottleneck identification was guesswork — developers were optimizing the wrong paths while true hotspots remained undetected.

Methodology

• cProfile + SnakeViz — full call-stack timing; flame graphs to identify dominant call chains.
• N+1 detection — resolved with select_related() and prefetch_related(), collapsing hundreds of queries into single optimized calls.
• EXPLAIN ANALYZE — identified sequential scans; created B-Tree composite indexes on FK and date range columns.
• O(n²) → O(n) — replaced nested loops with set-based lookups and pre-computed dicts outside iteration.