DEV Community: hans

Bridging the Tracking Gap: Implementing Manual Returns for Retailers and Customers

hans — Mon, 16 Mar 2026 03:15:00 +0000

In the world of e-commerce returns, "Mail Returns" (where a customer ships a parcel themselves) are often a black hole. Because the system doesn't generate a label, there is no automatic tracking. No one knows where the package is, and the "he-said-she-said" over shipping proof becomes a support nightmare.

We recently tackled this by building a manual tracking flow that serves two distinct masters: Retailers needing oversight and Customers needing peace of mind. Here is how we built a unified tracking system across two different UIs with a shared backend.

The Problem: The "Mail Return" Black Hole

When a return is marked as Mail, the customer uses their own shipping method (e.g., national post or a local courier).

For Staff: They can't see when a return is coming or if it's even been sent.
For Customers: They have no way to "prove" they shipped it within the platform.
The Technical Gap: Since no label is generated by our system, no tracking data is auto-filled.

We needed a way for both parties to manually input Tracking Numbers and Courier Names into a shared source of truth.

The Architecture: One Logic, Two Gates

Instead of building two separate tracking services, we opted for a shared form object pattern. This ensures that whether a retailer updates a number or a customer does it, the validation and persistence logic remain identical.

1. The Backend Foundation

We leveraged a Shipment::UpdateForm object to handle the heavy lifting. This kept our controllers thin and our models clean.

Feature	Implementation Detail
Endpoints	`PATCH .../customer/shipment/tracking`	`PUT .../retailer/shipment_tracking`
Validation	Max 64 chars for tracking; Max 128 for courier; Alphanumeric only.
State Guard	Only allows updates if the return is in `pending` or `pending_action`.
Data Model	Updates `tracking_number` and `custom_courier_name` on the `Shipment` model.

Pro-Tip: Avoid heavy model callbacks. By performing the update within the Form Object’s submit method, we ensured that side effects (like invalidating cache) only happened when the form was actually valid.

The Frontend Implementation

Retailer Experience (React + Polaris)

In the retailer dashboard, we focused on speed and clarity for support agents.

Contextual UI: If the shipping method is "Mail," an "Add Tracking Number" button appears.
The Modal Flow: Clicking the button triggers a Polaris modal that pre-fills existing data if the agent is editing rather than adding.
Immediate Feedback: Upon saving, the app invalidates the return order query, triggering an instant UI refresh to show the new "Track" button (which links to the external tracking URL).

Customer Experience (Remix + React)

The customer-facing side needed to be more "walk-through" style. We integrated this directly into the Return Summary page.

Progressive Disclosure: We show the "Tracking Number" and "Courier" labels even if empty to signal that this information is expected.
Inline Editing: Instead of a modal, we used an inline form. The "Save" button remains disabled until both fields are filled to ensure data integrity.
I18n Ready: Since we operate globally, all labels (add_tracking_button_label, etc.) are served via the API to support multi-language storefronts.

Key Technical Takeaways

Shared Validation is King: By using a single Form Object, we prevented "data drift" where a retailer might be able to enter a character that a customer’s UI would reject.
Status-Awareness: Don't let users edit tracking after a return is "Completed" or "Cancelled." Hard-coding these guards into the service layer prevents API abuse.
The "Track" Button Logic: We implemented a fallback mechanism. The UI displays the custom_courier_name if present, but falls back to the system's courierName for legacy data, ensuring the "Track Shipment" link never breaks.

Final Thoughts

Manual tracking isn't just about adding a text field; it's about creating a reliable audit trail. By building a unified backend and tailoring the UI to the specific needs of retailers and customers, we turned a "black hole" into a transparent part of the return lifecycle.

Beyond Manual Coding: Implementing an Agentic CI/CD Workflow at PostCo

hans — Thu, 12 Mar 2026 03:15:00 +0000

In a high-growth startup environment like PostCo, the goal is always the same: Ship high-quality features, faster.

As a Junior Software Engineer, I quickly realized that traditional "manual" workflows—where every line of boilerplate and every initial refactor is typed by hand—are no longer the most efficient way to deliver value. Instead, I’ve been developing an "Agentic Workflow" that uses AI agents as force multipliers within our CI/CD pipeline.

The Problem: The "Boilerplate" Bottleneck

Most developers spend a significant portion of their day on repetitive tasks: setting up file structures, writing unit tests, or refactoring existing methods to fit new requirements. These tasks are necessary but often delay the critical "thinking" work.

The Solution: The 4-Stage Agentic Loop

Our workflow at PostCo is designed to automate the execution phase while keeping the "Intent" and "Quality Control" firmly in human hands.

1. Requirements and Context (Notion + Linear) Every feature starts with a deep dive. We use Notion for Implementation Docs that define the why and how. These are synced to Linear, providing a clear map for the development process.

2. Agentic Execution (GitHub + Claude) The moment a PR is created, a Claude Agent (Planner/Executor) analyzes the Implementation Doc and the existing codebase. It doesn’t just suggest code; it executes it, pushing a functional starting point to the branch.

3. The "Checker" Loop Code shouldn't just be written; it should be verified. We employ a second Claude Agent (Code Checker) that reviews the first agent’s work. They loop bidirectionally:

Executor pushes code.
Checker identifies logic gaps or style inconsistencies.
Executor refines the code.

4. The Human-in-the-Loop: Tech Lead Review Once the agents have iterated to a point of stability, the "Review" phase begins. I take the refined code and walk through it with my Tech Lead. This is where we discuss the "Big Picture"—scalability, edge cases the agents might have missed, and alignment with our broader engineering goals at PostCo.

By the time my Tech Lead sees a PR, the "noise" has been filtered out. The code is already linted, tested, and structurally aligned with the requirements. This allows our senior engineers to spend their time mentoring and architecting rather than correcting syntax or boilerplate.

In 2026, being a "good developer" isn't just about how well you write code—it's about how well you manage the systems that produce it. This agentic workflow is just the beginning of how we’re scaling our engineering efforts.

Syncing Rails Validations with Formik: A Practical Approach

hans — Tue, 10 Mar 2026 03:12:00 +0000

In many SaaS apps, we allow "placeholder" data during onboarding to reduce friction. But what happens when that data needs to be validated later? I recently tackled this at PostCo by building a bridge between our Rails backend and React frontend.

Key Technical Takeaways:

The Backend Validator: Don't just rely on presence: true. I created a PlaceholderValidator to check against specific strings like "Address pending" or "00000".
The Error Bridge: Formik expects a specific shape. I wrote a utility to transform Rails' errors.messages into a flattened object that Formik can consume, including a case-mapping layer.
The UX Trick: If a field has a placeholder, the user shouldn't have to delete it manually. I implemented a "clear on edit" utility that treats placeholders as "" in the UI, triggering immediate Yup validation.

Handling nested errors is messy, but a little bit of mapping logic goes a long way in making a Junior-built feature feel Senior-grade.