When I took over the Integrations department, I inherited a dumpster fire. Zero active integrations. A few churned customers. And a codebase so messy that understanding it felt like archaeology.
The module had no testing framework. It used custom parsing logic that grabbed values, calculated everything in one massive function, and then stuffed them into database-stored templates. Over time, as clients demanded custom logic, everything got crammed into the same file, no structure, no separation of concerns, no variable nomenclature, just an ever-growing ball of complexity.
The Hacky Beginning
My first task? Build a new integration for a completely different feature in record time. Like any overwhelmed dev, I did what seemed easiest:
- Duplicate everything
- Make minor modifications
- Add a router to pick the right path
Two critical flaws emerged immediately:
- The original code was already complicated
- The routing logic was based on client business logic, not product features
The Problem Statement
It took me a full week just to understand how the system worked. The actual integration took several more days. But the real bottleneck? Communication. Explaining to clients how the integration worked, what data we needed, and how our systems would talk to each other.
Our clients weren’t tech companies. They were manufacturing giants, pharmaceutical firms, paint manufacturers, clothing businesses. Legacy industries with a single tech lead managing all vendor relationships.
The Rebuild
Once I identified these problems, I knew we needed a complete architectural overhaul. Coming from a developer background, I obsessed over Developer Experience (DX).
Phase 1: Kill the complexity
Do not reinvent the wheel.
I ripped out the custom template parsing and replaced it with ERB (Ruby’s native templating engine). This alone made the codebase dramatically easier to work with.
Phase 2: Documentation as Code
Communication is the key
I introduced Swagger documentation for all available endpoints. This cut down my back-and-forth with clients significantly and gave them an always-up-to-date reference. No more outdated PDFs floating around emails.
This was critical because my clients weren’t typical SaaS companies. They were giant legacy businesses manufacturing, pharmaceuticals, paints, clothing. These tech leads understood how to get things done but often worked with implementation partners(we were also one of them) who preferred out-of-the-box solutions and expected us to adapt.
Every integration became a negotiation to find middle ground.
Phase 3: Standardise the Process
Structure is essential in building anything that thrives.
I documented everything:
- Integration requirements and processes
- Data specifications
- Sequential implementation steps
- Typical project timelines
A standard project flow now looked like this:
- Discovery call — understand the client’s business requirements
- Platform mapping — map their needs to our platform’s capabilities
- Solution design — figure out how their ERP works and design the right data flow between systems
Once solutioning was done, customer support joined for user training while I enabled ERP implementation partners to integrate with our platform.
Phase 4: Code Architecture Overhaul
If you are afraid to change something, it is clearly poorly designed.
I restructured the entire codebase using the Factory design pattern:
- A base class collated all data points into structured format
- Client-specific logic extended the base class
- Clear separation of concerns between clients
The trade-off? Templates became code. Every change required a developer who understood ERB. But we solved that later.
Phase 5: Testing Framework
Quality means doing it right when no one is watching
I implemented comprehensive tests to ensure internal product changes didn’t break existing integrations. This would also help us in safely migrating our existing clients on to the new architecture.
In integrations, data integrity is everything. A small mistake can cause operational havoc:
- Lost communication breaks operations
- Incorrect data creates inventory and/or audit issues
Phase 6: Migration with Client Collaboration
Coming together is a beginning; keeping together is progress; working together is success.
Started new integrations on the new architecture and slowly developed it to support all previous integrations. Migrating existing integrations to the new architecture was only possible through close client partnerships. There was no way to distinguish between client-specific logic and general logic without asking.
Client A was instrumental here. We worked together to identify what was truly their requirement versus general integration logic.
After months of iteration, we reached a milepoint where:
- New developers understood the codebase in one day
- Given clear requirements, a developer could implement a new integration with tests in 2–4 hours
Tech was no longer the bottleneck. Operations were.
Observability: The Missing Piece
A critical improvement was enhancing our logging infrastructure.
When debugging, we constantly needed to check what was sent and received. But clients rarely had logs of incoming requests. We needed logs for every outgoing request.
I noticed some logs were missing from our logging service. To make it robust, I introduced middleware that logged all inbound and outbound integration traffic.
Every request to any third-party system was now logged with:
- What we sent
- What we received
- Exact timestamps
This became an audit trail. We could map requests to entities, understand which services were used by which clients, and run usage queries. It was a game-changer for debugging and analytics.
The Self-Service Evolution
Our clients didn’t want to do work on their end. They constantly pushed for cosmetic changes on our side that made no sense for general integration patterns.
Every company implemented their ERP differently. Some used SFTP/FTP to save costs. Others preferred HTTP despite the price.
The next evolution was building a no-code layer so the Customer Success/implementation team could handle integrations without developers.
I built a no-code templating engine using the Florric gem. It parsed data inputs and placed values from mappings into custom API payloads. I added a UI showing all available data points for a client. Now the implementation team could build custom API mappings without touching code.
This also made us safer from cosmetic change requests as every cosmetic request would push integration timeline and/or incur extra cost to clients
Future Expansion — Pay-Per-Use Pricing
Armed with usage data, we were on track to introduce Pay-Per-Use pricing.
Previously, integrations were free, one-time setup fee or fixed-cost. Now we could charge based on usage, similar to SAP’s ERP API pricing model. Clients were already used to this from their existing systems.
The logging infrastructure gave us usage metrics to set fair pricing. We understood usage patterns, behaviors, and which integrations drove the most value.
The Outcome
Over nine months, the department evolved from dormant with zero clients to:
- 9+ active integrations
- Implementation time reduced from days to hours
- Self-serving integration builder for non-technical teams
- Complete audit logging and usage analytics
- Pay-per-use pricing model
This transformed integrations from a cost center into a scalable revenue stream.
Leading integrations taught me that it’s more than just code. It’s cross-functional coordination, customer communication, and relentless iteration. But at the core, it’s about building systems that scale, not just technically, but also operationally.
If you have made it to the end consider following for more such content.