The problem#
The business sells physical products through a custom storefront, Amazon, multiple eBay accounts, Walmart, Newegg, and direct channels. Inventory may be at a supplier, in transit internationally, at a domestic warehouse, transferring to FBA, or held by Amazon. Each marketplace has different identifiers, reporting windows, fee models, return behavior, advertising APIs, and settlement timing.
A generic commerce platform covers the common path. The hard work accumulates in the differences:
- one physical component may appear through several listing SKUs and pack sizes;
- marketplace financial activity can arrive days later than order activity;
- listing state and desired state can diverge silently;
- inventory ownership and location affect value and availability;
- a carrier label is an external side effect that cannot be repeated casually;
- advertising decisions depend on reports with retention limits and changing schemas;
- legacy tools, databases, and operator habits cannot all be replaced at once.
My role#
I designed and implemented most of the custom software in the platform, operated the business processes it supports, integrated the third-party services, deployed and maintained the production services, and evolved the architecture as the business and available technology changed.
Platform map#
Five domain clusters share one set of primitives:
- Customer and sales surfaces - the custom Django storefront, Amazon, multiple eBay accounts, Walmart, Newegg, direct and recurring sales, PayPal and Stripe.
- Commercial decision systems - dynamic pricing, competitive research, listing and catalog administration, advertising optimization, purchasing and inventory allocation.
- Operational execution - purchase orders and supply-chain workflow, warehouse and FBA inventory, order operations, shipping labels, returns, customer messages.
- Financial and evidence layer - the double-entry ledger, FIFO costing, settlement ingestion, Xero synchronization, the historical report archive, cash-flow aggregation.
- Reliability and leverage - health dashboards, cron and report monitoring, AgentLib and Code Agent, browser automation with agent-assisted repair.
Architectural evolution#
The platform was built incrementally alongside an active, revenue-generating business. Its current architecture is the result of five evolutionary stages:
1. Solve the immediate workflow
Early systems were pragmatic scripts, a custom storefront, local databases, and direct integrations. The priority was to make the business function and remove repeated manual work.
2. Connect the channels
As marketplace sales grew, the platform accumulated adapters, report ingestion, listing controls, shipment flows, returns, and operator interfaces. Shared identity and synchronization became harder than any one API call.
3. Formalize money and inventory
The bookkeeping platform introduced a shared double-entry ledger, append-only semantics, channel classification frontiers, FIFO inventory layers, physical-location transitions, and Xero reconciliation.
4. Optimize decisions
Advertising and purchasing systems used the normalized history for empirical scoring, simulation, constrained allocation, and controlled API updates. Pricing evolved from rules and emergency response toward a staged agentic pipeline.
5. Build leverage and safer intelligence
AgentLib and Code Agent accelerated new development. Agents were integrated through curated data contracts, bounded tools, evaluations, and human review rather than direct access to every production concern.
Hard problems the platform answers#
Identity across systems
Marketplace SKU, listing ID, ASIN, order line, physical component SKU, pack size, supplier code, accounting entry, and shipment ID are not interchangeable. Normalization and explicit mappings prevent financial and inventory distortion - a listing SKU is an offer, not a thing.
Time and completeness
Order time, transaction time, settlement time, report date, local business date, and accounting date have different meanings. A “day” is not safe to post merely because the clock passed midnight - the settlement frontier exists because of this.
Physical versus financial state
Inventory can move physically before all costs are known. Direct shipment can create an obligation before supplier settlement. Returns can alter stock and revenue on different timelines.
External side effects
Charges, label purchases, listing revisions, and accounting synchronization need idempotency, durable intent, and post-failure reconciliation. A blind retry can buy the same label twice.
Human exceptions
Operators need to inspect, override, retry, and understand. Interfaces and audit trails are part of correctness, not afterthoughts.
Reliability model#
Patterns repeated across the estate:
- local durable state around unreliable APIs;
- natural-key and occurrence-based deduplication;
- append-only histories and explicit correction paths;
- work claims with leases and abandoned-work recovery;
- desired-state tables separated from API mutation;
- overlapping refresh windows for late-arriving reports;
- health check-ins, cron-log collection, and visible dashboards;
- reconciliation against independent sources;
- human review for low-confidence or high-consequence decisions.
Where AI fits#
The platform does not make “AI” the database or the workflow engine. It uses agents where interpretation adds value: pricing judgment over curated evidence, product and competitor research, email classification after deterministic routing, listing and photo assistance, self-healing browser automation, and software development itself.
Deterministic code remains responsible for source-of-truth state, data normalization, policy gates, identity, money, and side effects.
Retrospective#
The most important lesson is that business software is a model of obligations, not merely records. A sale creates promises to a customer, a marketplace, a carrier, inventory, accounting, and often a supplier. Systems become durable when those obligations, their timing, and their repair paths are explicit.
The platform coordinates daily operations across sales channels, purchasing, inventory, finance, fulfillment, and customer service for a multimillion-dollar ecommerce business.