How AI Accelerated the Eclipse In-Store Returns Application
A practical account of using Codex for architecture, implementation, debugging, verification, deployment, and engineering continuity.
OVERVIEW
Executive Summary
The Eclipse In-Store Returns application is a real digital-commerce system that connects store associates, head-office reporting, device authorization, Shopify refunds, a middleware database, associate imports, and an Aptos inventory feed. The AI experiment was not a single prompt that produced a finished application. It was a sustained collaboration in which the engineer defined the goal, supplied domain context, reviewed decisions, tested the product, and progressively tightened the instructions while Codex analyzed, implemented, verified, and documented the work.
CORE FINDING AI created the most value when it was treated as an engineering execution partner inside a controlled workflow: specification, plan, scoped change, test evidence, human review, and only then deployment.
109 backend tests passed
Latest complex bug-fix validation; one existing live-Shopify test remained intentionally skipped.
10/10 browser regressions passed
Desktop Chrome and a Pixel 5 mobile viewport.
200 production health response
The deployed application and transactions route were checked after the new bundle became live.
What the Experiment Demonstrated
- AI can preserve and recover complex project context across specifications, code, test evidence, and task history.
- AI can move from ambiguous bug reports to root cause, implementation, regression coverage, browser checks, and deployment evidence.
- Human judgment remains essential for business rules, production authorization, risk acceptance, secrets, and deciding when evidence is sufficient.
PROBLEM
01 / The Task and Why It Was Complex
The business objective was to replace a fragmented in-store return process with a standalone web application that feels familiar to Shopify users while enforcing Eclipse-specific controls. Store associates needed to find an order, identify only eligible physical items, choose quantities and reasons, submit a Shopify refund, and produce records for head-office reporting and downstream inventory processing.
| Complexity Area | What Had to Work | Why It Raised Risk |
|---|---|---|
| Commerce integration | Shopify order lookup, refund calculation, refund creation, and notification. | A defect can create an incorrect financial transaction. |
| Identity and access | Device registration, associate login, store binding, role guards, and session expiry. | Incorrect access can expose customer or operational data. |
| Eligibility rules | Shipped quantity, prior refunds, and non-physical product restrictions. | A UI-only check can be bypassed by a direct API request. |
| Operations | Head-office reports, CSV/PDF exports, associate imports, and Aptos files. | Silent data errors can create incorrect business decisions. |
| Quality | Backend tests, browser flows, responsive behavior, screenshots, and production checks. | Passing unit tests alone does not prove the user journey. |
The Starting Material
- A functional specification and a separate device-access-control document.
- A development plan with eight modules, API contracts, data models, risks, and acceptance criteria.
- A growing codebase with React, Vite, Shopify Polaris, Node/Express, MongoDB, Shopify Admin API integration, and scheduled Aptos feed work.
- Open business decisions, incomplete environment access, and real production constraints.
CHALLENGE The source plan described one target architecture, while the implemented application evolved through real constraints. AI had to inspect the current repository and evidence instead of blindly repeating the original plan.
METHOD
02 / How We Conversed With AI
The conversation improved as the prompts became more concrete. The strongest requests provided the current state, the expected outcome, constraints, test evidence, and a clear definition of completion. Instead of asking for code alone, the engineer asked for analysis, implementation, verification, and a handoff.
| Conversation Stage | Example Instruction | How AI Responded |
|---|---|---|
| Context recovery | Read the project context and explain what is complete and what remains. | Inspected durable project documents and created a structured status/handoff rather than relying on memory. |
| Exploratory QA | Open every page, find UI/UX problems, fix them, and retest. | Mapped routes, ran browser automation, fixed loading, pagination, routing, and filter behavior, then reran the crawl. |
| End-to-end proof | Test the full return flow using a specific order. | Discovered that the requested order was fully refunded, selected a valid alternative, found a toast-context defect, fixed it, and verified a real submission. |
| Precise bug report | Selected rows export all data; associate-name filter does not work. | Traced UI and API behavior, constrained exports by selected IDs, added name/number matching, and covered stale selection state. |
| Controlled release | Push and deploy only these fixes; do not update Jira. | Scoped the commit, preserved unrelated changes, deployed, and verified the live asset and health endpoint. |
The Repeatable Interaction Pattern
- State the business outcome and the affected user journey.
- Provide exact reproduction steps, screenshots, files, and known constraints.
- Ask AI to investigate before editing and to explain the root cause.
- Require tests at the API and browser layers, including responsive behavior where relevant.
- Review locally, provide feedback, and authorize deployment only after the behavior is confirmed.
OPERATING MODEL
03 / How AI Helped Across the Lifecycle
Specification and Planning
AI consolidated the functional specification and device-control requirements into eight delivery modules. It also separated confirmed facts from open business decisions so guessed policy values did not become code.
Architecture and Code Navigation
AI used repository instructions and code intelligence to locate the owning routes, pages, and services. Risky eligibility rules were enforced during both lookup and submission.
Implementation and Debugging
AI changed backend services, API routes, React pages, translations, and tests. Validation also exposed adjacent defects, including stale selections and a Polaris toast-context error.
Testing and Evidence
The collaboration combined backend tests, builds, desktop/mobile Playwright checks, manual browser review, screenshots, and production verification.
Continuity and Documentation
AI produced handoffs, environment requirement lists without secret values, QA plans, and status recalls, reducing the cost of resuming work after long gaps or account changes.
HUMAN ROLE The engineer remained accountable for domain interpretation, supplying access and test data, reviewing the UI, correcting assumptions, protecting credentials, and deciding when deployment was authorized.
CASE STUDY
04 / Deep Dive: A Complex Bug-Fix Run
The clearest example began with two user-visible defects on the head-office Transactions page: exporting after selecting rows still exported the full result set, and filtering by an associate name returned no match. The work expanded into a controlled, end-to-end engineering run.
Root Cause
- The export URL was built from active filters but did not include the selected transaction IDs.
- The Associate filter sent one field and the backend matched only associateNumber, so a name such as “Maya” could never match.
- Polaris preserved internal selection state after filter changes, creating a risk that invisible older selections could affect a later export.
Implementation
- Checked transaction IDs became an explicit CSV/PDF export constraint.
- The backend added safe ObjectId validation, preventing malformed selections from falling back to an unrestricted export.
- Associate filtering became partial and case-insensitive across both name and number.
- Selection clearing was tied to filter and pagination actions so the exported set always matched the visible context.
Verification
| Layer | Evidence |
|---|---|
| Backend | 109 tests passed; selected-ID CSV/PDF constraints and name/number matching covered. |
| Frontend build | Production build passed. |
| Browser | 10/10 Playwright checks passed across desktop Chrome and Pixel 5. |
| Manual review | Checked-row state, filtered results, download requests, and console errors were inspected. |
| Production | The tested commit was deployed; new bundle served; health and transactions route returned HTTP 200. |
WHY THIS MATTERS AI did more than implement the reported behavior. It identified an adjacent state-management failure, challenged its own browser assertion, distinguished a hidden accessibility node from the real UI state, and refined the test to validate the actual export contract.
PROOF
05 / Visual Evidence From the Working Application
The application evidence demonstrates that the experiment produced a working operational surface, not only code changes. The head-office dashboard combines refund metrics, recent transactions, device status, associate counts, and Aptos feed activity.
PROOF
The Store Return Journey
The store workflow distinguishes refundable items from already-refunded items, calculates a preview, requires a return reason, and protects customer information in the training evidence. This screen was exercised through browser automation and the end-to-end refund flow.
REFLECTION
06 / Outcomes, Challenges, and Lessons
What Worked Well
- Long-running context: AI connected specification details, project state, code, screenshots, tests, and deployment evidence.
- Layered verification: backend, build, browser, mobile, manual review, and production checks caught different classes of defects.
- Scoped autonomy: explicit constraints such as “only these files” and “do not update Jira” kept the release aligned with intent.
- Continuity artifacts: handoff and QA documents made future sessions safer and faster.
What Was Partially Successful
- Automation occasionally encountered stale local servers, port conflicts, or tooling/index version mismatches.
- Some first-pass browser assertions failed because component libraries expose duplicate accessibility text.
- The original architecture plan and the implemented stack diverged, so current repository evidence had to override stale assumptions.
What AI Could Not Decide
- Final return-window policy, audit-period definition, target-environment testing authorization, and client-owned Aptos details.
- Whether production risk was acceptable and whether a deployment should proceed.
- Credentials, account permissions, and secret rotation; those remain human- and system-owned responsibilities.
NEXT PRACTICE
07 / A Reusable Playbook for Future AI Experiments
The following prompt structure can be reused for bug fixes, integrations, UI work, and long-running engineering tasks.
PROMPT TEMPLATE Goal: [business outcome]. Current behavior: [what happens]. Expected behavior: [what should happen]. Evidence: [steps, screenshots, files, logs]. Constraints: [systems/files/actions not to touch]. Required workflow: investigate → explain root cause → assess impact → implement → test → show evidence. Completion means: [specific tests and review gates].
Review Gates
- Before implementation: confirm scope, assumptions, affected flows, and business risk.
- Before handoff: run the relevant tests and inspect user-facing behavior.
- Before deployment: verify the exact commit and preserve unrelated workspace changes.
- After deployment: check the live bundle/version, health endpoint, and critical route.
Conclusion
The EC Return experiment demonstrates a practical shift from AI as a question-answering tool to AI as a supervised engineering collaborator. Its strongest contribution was not any single code change; it was the ability to connect planning, implementation, testing, debugging, deployment, and documentation into one traceable workflow. The resulting productivity gain came from pairing machine execution with human specification, judgment, and accountability.
FINAL TAKEAWAY The competitive advantage is not simply access to AI. It is the operating model around AI: clear specifications, safe environments, reviewable changes, reliable evaluations, and evidence that the business outcome was actually achieved.