FBA Supply Chain Automator — Request for Proposal (RFP) & System Capabilities Specification

Document Version: 16.0 (Century Capstone | 100 Modules) (Living System Specification)
Runtime Stack: Java 25 LTS | Spring Boot 4.1.1 (Spring Framework 7 / Jakarta EE 11) | Gradle 9.8.2
Persistence Layer: H2 File-Persisted PostgreSQL-Compatible SQL (./data/supplychain) & Production PostgreSQL 17
Deployment Targets: Local Zero-Cost Workstation ($0 API Mode), Docker Container (EC2 / Lightsail), and AWS Lambda Serverless Handlers

1. Executive Summary & System Vision

The FBA Supply Chain Automator is an end-to-end, deterministic e-commerce supply chain, procurement, treasury, quality control, customs/freight optimization, regulatory compliance, storage arbitrage, customer returns governance, live policy/rate shock governance, geopolitical tariff horizon & Chinese New Year blackout buffering, FBA inbound shortage reconciliation, Buy Box hijacker defense, multi-currency FX & wire rail arbitrage, promo discount-stacking protection, dimensional-weight packaging optimization, Multi-Channel Fulfillment (MCF) off-Amazon arbitrage, supplier SLA & defect clawback credit memos, M&A brand exit valuation, competitor price-war & stockout anomaly radar, US Customs 19 U.S.C. § 1313 duty drawback recovery, virtual bundle & multipack AOV expansion, Amazon AWD vs. 3PL staging arbitrage, Subscribe & Save (SnS) LTV modeling, aged inventory liquidation & surcharge optimization, maritime chokepoint dynamic air-bridging, Amazon Brand Referral Bonus external advertising ROI, Amazon Vine review velocity payback, 2025/2026 FBA Inbound Placement Fee split optimization, Section 321 De Minimis policy sunset modeling, US corporate quarterly tax & IRC § 471 COGS reserves, Amazon $1M CGL & marine cargo insurance compliance, Amazon Manage Your Experiments A/B test analytics, autonomous CSCO daily executive briefings, customer buyer-seller VOC defect shields, Amazon Transparency 2D serialization, ocean container demurrage shields, global multi-region VAT/EPR cross-border expansions, Amazon FBA auto-filing reimbursements, multi-echelon dual-variance safety stock, dynamic price elasticity repricing, inventory financing credit revolvers, autonomous Gemini Flash conversational AI copilot, official Amazon Seller Central 1-Click OAuth2 authentication wizard, autonomous live Amazon SP-API sync scheduler & catalog ingestion engine, multi-modal AI listing vision & packaging inspector studio, live production cutover governance, bi-weekly settlement reconciliation, and advertising automation platform purpose-built for private-label Amazon Fulfillment by Amazon (FBA) operations.

Core Engineering Principles

1. Zero-API-Key Local Operability ($0 Startup Mode): Every module works out of the box using manual paste-in analyzers, CSV importers/exporters, and realistic sandbox adapters.
2. Strict Financial Precision (BigDecimal Only): All monetary values, weights, dimensions, tariffs, FBA fees, CBM/cubic-foot volumes, FX rates, SDE multiples, duty drawback refunds, and margin percentages are computed exclusively using java.math.BigDecimal with RoundingMode.HALF_UP (zero double or float rounding drift).
3. Human-in-the-Loop (HITL) Capital Governance: The system automates 100% of math, forecasting, defect extraction, and label preparation, but places a mandatory approval gate (AWAITING_APPROVAL) before committing real cash to factory Purchase Orders.
4. Closed-Loop Pipeline Continuity: Data flows seamlessly across 100 specialized Java modules and 108 persistent SQL tables.

2. System Architecture & Module Capabilities Matrix (100 Modules)

3. Relational Database Schema (59 SQL Tables)

All entities persist automatically to ./data/supplychain.mv.db (H2 PostgreSQL compatibility mode locally; PostgreSQL 17 in production):

1. candidate_products (asin PK): Discovered Amazon product opportunities, Buy Box prices, BSR, review metrics, defect summaries, factory upgrade prescriptions, opportunity scores, and bookmark flags.
2. product_launch_packs (asin PK): Generated Amazon SEO titles, 5 bullet points, backend search terms, and Day-1 Exact Match PPC launch keywords.
3. supplier_quotes (id UUID PK): Factory quotations from Alibaba/1688/CJ, MOQ, COGS, prep fees, Air/Sea batch freight, calculated all-in landed costs, net margins, and selected winner status.
4. quality_inspections (id UUID PK): Pre-shipment ISO 2859-1 (AQL 2.5/4.0) inspection logs, critical/major/minor defect counts, drop test & FNSKU scan results, master carton dimensions/weights, FBA 25"/50lb compliance flags, and 70% payment release verdicts.
5. sku_compliance_records (sku PK): US Customs 19 U.S.C. 1304 Country of Origin marking verification, USDA APHIS Lacey Act PPQ 505, FDA 21 CFR Food Contact certs, UL/CPC lab safety reports, USPTO Brand Registry, and Amazon Transparency anti-hijacker flags.
6. mvp_launch_batches (sku PK): 100-unit fast-validation test batch traffic, conversion, TACoS, capital recovery, and Go/No-Go graduation metrics.
7. active_skus (sku PK): Active catalog inventory (available + inbound FBA units), 7d/30d sales velocity inputs, production/freight/prep lead times, safety stock days, MOQ, landed cost, and current retail price.
8. purchase_orders (id UUID PK): Physical inventory purchase orders, state machine status, supplier references, 3PL receipt IDs, FBA inbound plan IDs, and UPS/carrier tracking numbers.
9. ppc_decision_logs (id UUID PK): Immutable audit log of every automated search term negation, bid reduction, and exact-match promotion decision.
10. return_defect_audits (id UUID PK): 30-day SKU customer return root-cause breakdowns, NCX defect rates, Amazon-fault carrier damage reimbursements, VoC suspension risk statuses, and CAPA plans.
11. policy_rate_schedules (rate_key PK): Live configurable regulatory tariff rates, FBA fulfillment/storage fee benchmarks, freight spot benchmarks, review cadences (14d/30d/90d), official source references, and last-verified timestamps.
12. sku_settlement_ledgers (id BIGINT PK): Bi-weekly Amazon settlement payout reconciliations per SKU, expected vs. actual deducted Amazon fees, hidden fee leakage amounts, net bank deposits, landed COGS sold, realized net profit/margin, and audit status.
13. geopolitical_tariff_events (event_code PK): Upcoming 30/60/90-day USTR/CBP political tariff notices, affected HTS prefixes, current vs. proposed duty %, days until effective, enactment probability %, and Federal Register docket references.
14. global_supply_calendar_events (event_code PK): Global factory and logistics blackout events (Chinese New Year, Golden Week, Q4 FBA receiving rush), additional production/freight delay days, and peak surcharge percentages.
15. fba_inbound_discrepancies (fba_shipment_id PK): FBA inbound shipment receiving audits, shipped vs. checked-in unit counts, missing shortage reimbursements owed, signed BOL/invoice doc flags, 60-day window status, and Seller Support claim packets.
16. buybox_hijacker_incidents (id BIGINT PK): Unauthorized 3P seller incidents, Buy Box win rate drops, daily lost revenue, Test-Buy Order IDs, and generated Cease & Desist + Brand Registry takedown filings.
17. fx_supplier_hedges (id UUID PK): Supplier USD/CNY exchange rate baselines vs. spot rates, implied fair USD FOB prices, FX negotiation savings, and fintech local CNH vs. SWIFT bank wire fee arbitrage.
18. promo_deal_simulations (id BIGINT PK): Promotional deal & coupon simulations, discount stacking detection flags, $0.60 clip fee deductions, post-promo net margins, and required velocity lift multipliers.
19. packaging_optimization_audits (id BIGINT PK): SKU packaging dimensional weight audits, current vs. target FBA size tiers, recommended sub-inch box trims, and annual FBA/freight savings.
20. mcf_channel_evaluations (id BIGINT PK): Off-Amazon Multi-Channel Fulfillment (MCF) & Walmart WFS channel profit comparisons against Amazon FBA.
21. supplier_clawback_credits (id BIGINT PK): Supplier SLA & defect clawback credit memos combining return/AQL defect recovery and late delivery air-bridge penalties.
22. brand_exit_valuations (id BIGINT PK): Portfolio M&A exit valuations, Trailing 12-Month SDE, multiple expansion scorecards (2.50x–4.25x), and total deal proceeds including inventory at cost.
23. competitor_anomaly_radars (id BIGINT PK): Competitor price changes, estimated stock levels, star rating drops, anomaly classifications, and tactical repricing/PPC conquest playbooks.
24. customs_duty_drawbacks (id BIGINT PK): CBP Form 7501 import entry summaries, NARF/foreign exported units, 99% 19 U.S.C. § 1313 recoverable tariff amounts, and net cash refund claims.
25. virtual_bundle_simulations (id BIGINT PK): Pre-packed multipack and Amazon Virtual Brand Bundle unit economics, single-PPC-click AOV amortization, and per-order profit lift.
26. system_cutover_checks (integration_key PK): External API subsystem cutover readiness checks, environment variable mappings, and $0 Zero-Key vs. Live Production operating statuses.
27. awd_staging_evaluations (id BIGINT PK): Amazon AWD upstream bulk pallet storage vs. private 3PL warehouse evaluations and FBA low-inventory fee waivers.
28. sns_retention_simulations (id BIGINT PK): Subscribe & Save customer LTV, repeat auto-delivery $0 PPC CAC margins, and seller discount tier optimizations.
29. aged_inventory_liquidations (id BIGINT PK): 181–365+ day aged storage surcharges, Outlet Flash Sales, Amazon Bulk Liquidation (8% gross), and removal order optimization.
30. maritime_route_disruptions (id BIGINT PK): Red Sea/Panama/Port congestion delay tracking, dynamic ocean ROP buffers, and partial Air-Bridge margin calculations.
31. brand_referral_attributions (id BIGINT PK): TikTok/Meta/Google external ad campaigns, 10% Amazon Brand Referral Bonus rebates, 14-day halo sales, and true net CAC vs. native PPC.
32. vine_launch_simulations (id BIGINT PK): Amazon Vine review velocity tiers ($0/$75/$200), product giveaway costs, and daily PPC waste avoided from CVR gains.
33. inbound_placement_optimizations (id BIGINT PK): 2025/2026 Amazon Inbound Placement fees comparing Single-FC Minimal Splits vs. 5-Way Regional Splits.
34. section321_policy_simulations (id BIGINT PK): 19 U.S.C. § 1321 De Minimis $800 threshold sunset shocks on cross-border direct-air rivals and market share capture.
35. us_corporate_tax_reserves (id BIGINT PK): IRS Forms 1040-ES / 1120-W quarterly estimated tax schedules, IRC § 471 unsold inventory asset capitalization, and 20% § 199A QBI deductions.
36. cargo_and_liability_policies (id BIGINT PK): Section 9 BSA $1M Commercial General Liability insurance audit and 110% All-Risk Marine Cargo COGSA gap elimination.
37. manage_experiments_tests (id BIGINT PK): Amazon Manage Your Experiments A/B split-tests, two-proportion Z-score confidence (95%+), and annualized net profit lift.
38. autonomous_daily_briefings (id BIGINT PK): Chief Supply Chain Officer (CSCO) autonomous morning briefings, bank liquidity, 30d PO commitments, cash recoveries, and tactical action items.
39. hitl_alert_logs (id UUID PK): Immutable audit log of every Human-in-the-Loop capital approval alert and defensive repricing action dispatched to operators.
40. buyer_seller_messages (id BIGINT PK): Customer inbound messages, Voice of Customer defect category, sentiment scoring, and Amazon policy-compliant reply drafts.
41. transparency_serial_batches (id BIGINT PK): Amazon Transparency 2D serialization ranges, factory sticker application audits, and reconciliation discrepancy detection.
42. ocean_demurrage_shields (id BIGINT PK): Ocean maritime container terminal free-time tracking, daily demurrage/detention per-diems, and off-dock staging pull decisions.
43. global_marketplace_expansions (id BIGINT PK): Cross-border marketplace expansion simulations (UK, EU, CA, JP) with destination VAT/GST, EPR eco-packaging contributions, and FX conversions.
44. fba_reimbursement_claims (id BIGINT PK): Amazon FBA inventory reimbursement claims, claim reference codes, SKU, claim types, discrepancy units, estimated value per unit, total claim amount, and filing statuses.
45. multi_echelon_safety_stocks (id BIGINT PK): Dynamic multi-echelon safety stock evaluations, CSL service level targets (95%, 98%), Z-scores, lead time and demand standard deviations, recommended buffer units, and ROPs.
46. price_elasticity_experiments (id BIGINT PK): Price elasticity experiments, baseline/test prices and velocities, unit COGS, calculated elasticity coefficients, baseline vs test gross profits, daily profit deltas, and pricing verdicts.
47. working_capital_revolvers (id BIGINT PK): Revolving credit facility drawdowns, credit limits, drawn balances, interest rates, financed PO amounts, days to Amazon payout, interest expense, and net ROI verdicts.
48. copilot_chat_history (id BIGINT PK): Immutable audit trail of conversational supply chain copilot interactions, user prompts, detected intent classifications, and model responses (GEMINI_1_5_FLASH vs LOCAL_DETERMINISTIC_ENGINE).
49. amazon_store_credentials (seller_id PK): Encrypted AES-256 vault storing authorized Amazon Seller Central credentials, LWA refresh tokens, rotated access tokens, token expiration timestamps, and live health diagnostics.
50. amazon_sync_job_logs (id BIGINT PK): Immutable audit log of autonomous Amazon SP-API inventory synchronization runs, SKU update counts, reconciled order units, defensive price hike triggers (+12%), auto-drafted replenishment PO counts, and execution durations.
51. image_inspection_audits (id BIGINT PK): Multi-modal AI vision inspection audits, Amazon TOS RGB (255, 255, 255) pure white background verifications, factory master carton drop-test evaluations, barcode legibility checks, and 7-module A+ Content visual storyboards.
52. niche_discovery_scans (id BIGINT PK): Autonomous category niche scans, opportunity scoring (0-100), and reverse-ASIN keyword extractions with CPC bid caps.
53. factory_negotiations (id BIGINT PK): Bilingual Chinese supplier RFQs (询价函), volume price tier curves (1k/2k/5k MOQ), and ISO 2859-1 AQL 2.5 quality protocols.
54. facility_stations (station_code PK): Pre-registered physical warehouse dock bays and pack stations (FAC-LAX-01::BAY-14, BAY-01, CONV-02) with hardware terminal bindings.
55. dock_scans (id BIGINT PK): Contactless 3PL receiving scans, barcode payloads, scanned box weights, operator badge IDs, station codes, and high-resolution photo evidence.
56. customer_review_requests (order_id PK): Automated post-purchase review solicitations, sentiment scores, refund suppression flags, and dispatch scheduling.
57. transparency_codes (serial_code PK): Individual unit-level Amazon Transparency 2D serial numbers, security hashes, scan logs, and counterfeit detection flags.
58. ocean_container_demurrage (container_number PK): Maritime ocean container terminal free-time tracking, demurrage/detention clocks, and off-dock drayage drop-yard pull actions.
59. global_expansion_simulations (id BIGINT PK): Multi-region Amazon UK, DE, and JP cross-border simulations with VAT, EPR waste fees, and FX rate modeling.

4. Complete REST API Specification (145+ Endpoints)