Headless project rescue

fixing what others left broken

We helped a struggling headless e-commerce project move from instability to a reliable, scalable platform, fixing what others broke.

About the project

The client approached us to take over an ongoing e-commerce project built on a headless, modular architecture.

Medusa.js

For backend product and order management

Next.js

For frontend and landing pages

Strapi CMS

For whole content management

Despite over 2,500 development hours already invested by a previous agency, the system was far from ready for everyday business operations. The platform suffered from failed transactions, broken product data, malfunctioning integrations, and lacked even basic deployment and documentation processes.

With customers impacted and business at risk, the client needed immediate technical stabilization, fast. They needed a partner who could stabilize the system, restore control over environments, and give the platform a reliable foundation for future growth.

The challange

When we stepped in, the situation was urgent.

The previous agency put in over 2,500 development hours a year, and yet the store was struggling with serious issues.

.

Broken key functionalities

Product feeds, vouchers, shipping methods

Critical checkout failures

500 errors on Product Pages

Hard-coded logic

For every product variants

No proper documentation

Missing configuration files, no working local or staging environment

Validation issues

In forms - every field validated incorrectly

Synchronization problems

Between PCMarket ERP and Medusa database

Missing Git commits

For production changes

Unstable SSR*

*Server-Side Rendering on the frontend

Instagram feed

Was broken with multiple uploads

The frontend and backend were misaligned, the infrastructure was chaotic, and basic maintenance tasks were risky.

The store was barely holding together, with bugs affecting real customer experiences.

Our solution

We approached the project systematically, treating it as a full rescue operation.

First – takeover and stabilization

Within the first 50 hours, our development and DevOps team:

All of this was done without any initial project documentation, no .env files, no README, and no working staging setup – purely based on code inspection and recovery best practices.

This allowed us to stabilize the most urgent issues without putting the live store at risk.

Second – fixing technical problems layer by layer

We performed a complete technical audit across the backend, frontend, and infrastructure layers.

The Medusa.js backend, although promising, had been left in a fragile state:

API stability issues

Data returned by PCMarket ERP was often inconsistent, but the backend lacked proper validation and transformation logic. We created a reliable adapter that transformed incoming ERP data into clean Medusa product models.

Authentication and authorization risks

Sensitive user data was logged to production consoles, posing a security threat. We reworked the logging system to exclude personal data and cleaned up insecure endpoints.

Synchronizing 160,000+ products

The ERP-to-Medusa sync process failed during full runs due to insufficient server resources. We diagnosed and resolved the issue by expanding the server’s RAM allocation on Digital Ocean, enabling full synchronization within around 4 hours.

Hard-coded integrations

We refactored key integrations (like Autopay and Apaczka) to avoid hard-coded assumptions, ensuring modularity and easier future upgrades.

Untracked production changes

Some critical changes were made directly on the production server, not pushed to Git. We audited and reconciled those differences to ensure version control integrity.

The Next.js 14-based frontend also faced critical reliability and UX issues:

Broken form validation

Forms validated all fields at once, regardless of user interaction, making forms unusable. We refactored the logic using Formik and Yup, ensuring fields are validated independently and clearly.

Outdated Next.js setup

Although the app migrated to Next.js 14, it was incomplete. Critical hydration errors and broken middleware were causing performance and SEO issues. We stabilized SSR (Server-Side Rendering) and fully adapted the app to the App Router model.

Broken gallery and image handling

The product gallery relied on a faulty ResizeObserver implementation, causing layout glitches and visual jumps. We reworked the gallery rendering to properly handle viewport and image size recalculations.

Hard-coded variant logic

The original store assumed that every product variant must have all attributes, leading to errors during checkout. We updated the logic to allow flexible variant management.

Feed errors

The Instagram product feed and Google Shopping product feeds were non-functional, blocking external marketing integrations. We fixed serialization and feed formatting to restore these channels.

The CMS used for managing marketing content – Strapi – needed updates and cleanup:

Rich text editor issues

The previous editor setup caused formatting inconsistencies. We implemented a customized version of CKEditor 5, restricting available formatting options to match branding guidelines and ensuring clean, valid HTML output.

Versioning and publishing

Draft/publish logic was inconsistent. We improved workflows so that content editors could reliably manage live and upcoming updates without risking unintentional overwrites.

SEO and content blocks

We reorganized Strapi's data models to better support dynamic SEO metadata, CTA blocks, and reusable components across the site.

The system’s environment management was in a critical state when we took over:

Broken or missing deployment automation

Deployment to production required manual server intervention every time. We introduced basic CI/CD pipelines for backend and frontend to automate builds, tests, and safe releases.

Environment variable chaos

Vercel had dozens of unnecessary, unused, and sometimes duplicated environment variables. We cleaned them up, standardized naming, and ensured clear separation between staging and production environments.

Missing environment files

The project lacked .env files for both staging and production. We rebuilt the configurations from scratch, based on analyzing deployed apps.

Branch synchronization problems

Code branches for staging and production had drifted apart dangerously. We manually audited and synchronized them to avoid regression risks.

All of this was done without any initial project documentation, no .env files, no README, and no working staging setup – purely based on code inspection and recovery best practices.

This allowed us to stabilize the most urgent issues without putting the live store at risk.

Technologies we used

  • Frontend

    Next.js 14 (with SSR/ISR), React, TailwindCSS, Formik

  • Backend

    Medusa.js (Node.js), TypeORM, REST API integrations

  • CMS

    Strapi v4 with customized rich text editor (CKEditor 5)

  • Databases

    PostgreSQL (separate for Medusa and Strapi)

  • Integrations

    •   PCMarket (ERP) for product and stock synchronization
    •   Autopay for payment processing
    •   Apaczka for logistics (shipment labels, pickup point maps)

  • Infrastructure

    •   Vercel for frontend builds and deployments
    •   Digital Ocean VPS for backend services (Docker-based deployment)
    •   EasyPanel for server management and deployments

Project in numbers

We used a Kanban project management approach, with weekly updates and close collaboration with the NFC Wear team to ensure fast delivery and clear communication.

0 h+

Spent by the previous agency (before takeover)

0 h

for full project takeover and first fixes

0 h+

Spent to stabilize the platform

0 +

Tasks completed during rescue and optimization

0 +

Products synchronized from external ERP (PCMarket)

The outcome

After a few months of intensive work, the project landscape changed completely:

Stabilized production store

ready for ongoing operations

Fully working staging environment

synchronized with production

Reliable CI/CD pipelines

making deployments faster and safer

Fixed critical bugs

affecting customer experience and revenue

Clear project structure

enabling easier maintenance and future development

Most importantly, the client now has full control over their platform, with significantly reduced operational risk compared to the chaotic state we inherited.

Comment from the expert:
In the same amount of time (~300 hours), the client could have replatformed entirely to a clean Shopware 6 setup, with a fully working store and significantly more modern features. However, stabilizing the current system was necessary first due to operational risks.

We deliver results where others fail

If you’re looking for a partner who can stabilize, optimize, and grow your system – let’s discuss your needs.

+48 663 601 422

Phone

bartosz.guzdziol@speardevs.com

E-mail

We will process your personal data to review and answer your inquiry. SpearDevs sp. z o.o. with its registered office in Poznań, Poland is the data controller of your personal data. For more information please visit our privacy policy.