Skip to content

VERSION_ROADMAP.md

Latest commit

 

History

History
306 lines (235 loc) · 25 KB

VERSION_ROADMAP.md

File metadata and controls

306 lines (235 loc) · 25 KB
Raw

OrderFlow: 10-Version Build Roadmap

A Prompt-Ready Development Plan

This document breaks the full system (see SYSTEM_DESIGN.md) into 10 sequential versions. Each version is self-contained, builds strictly on the previous one, and ends with a working, testable app. Each version includes: Goal, Scope, Data model changes, Backend (Rust) deliverables, Frontend deliverables, Acceptance criteria, and a Suggested AI prompt you can paste (with light editing) into your coding assistant.

How to use this: Feed the AI SYSTEM_DESIGN.md as context in every session, then the version block you are building. Never skip acceptance criteria; they are the definition of done. If a version's prompt output drifts from the design doc, the design doc wins.

Version Map at a Glance

V Codename Theme You can, after this version...
1 Foundation App shell, DB, stores Create/manage stores in a polished dark shell
2 Intake Orders + Shopify sync See real Shopify orders flow in automatically
3 Confirm Confirmation engine Work the WhatsApp/call queue and confirm/deny orders
4 Ship Packaging + tracking Enter tracking IDs and move parcels through transit
5 Deliver Delivery outcomes + returns Log courier attempts, handle rejections and returns
6 Money Wallet + COD collection Collect cash, see the ledger, recharge/withdraw
7 Recurring Subscriptions Track Shopify/Canva/etc. monthly costs against the wallet
8 Ads Ad tracking + hidden tax Log daily spend per ad, per platform, with effective cost
9 Insight Analytics channel See graphs, funnels, ROAS, and profit per store + globally
10 Polish Design system finale Ship-quality dialogs, empty states, backups, exports, keyboard flow

Dependency chain: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10. Versions 7 and 8 could technically swap, but keep the order for wallet coherence (ads post wallet transactions, which need V6).

Version 1: Foundation

App shell, database, multi-store management

Goal. A running Tauri app with the complete visual identity, the SQLite layer wired through Rust, and full store CRUD. No orders yet. This version sets the design DNA everything else inherits.

Scope.

  • Tauri 2 project scaffold: React + TypeScript + Tailwind + Framer Motion frontend, Rust backend with sqlx + SQLite (WAL mode, foreign keys on), migrations system.
  • Design tokens implemented as CSS variables per §13 of the design doc (near-black zinc palette, violet accent, Inter + JetBrains Mono, radius scale).
  • Core layout: collapsible sidebar with store switcher, main content area, blur-fade page transitions.
  • Store management: create, edit, archive stores (name, currency, accent color). Store settings page with placeholder sections for future settings.
  • Ctrl+K command palette for store switching.
  • Signature components built now, reused forever: ShimmerButton, BorderBeamCard, NumberTicker, StatusPill, AnimatedList, GlassDialog (basic confirm variant), Toast system, EmptyState.
  • Tables: stores, store_settings, wallets (created with store, balance 0).

Data model. stores, store_settings, wallets from §4.

Backend. IPC commands: stores::create/update/list/archive, system::app_info. Migration runner on startup.

Frontend. Sidebar layout, Global Overview page (bento grid of store cards, mostly placeholder stats), Store Settings page, Add Store flow with animated empty state ("animated beams" welcome screen when zero stores exist).

Acceptance criteria.

  1. App launches to a designed empty state prompting store creation.
  2. Creating a store persists across app restarts (SQLite verified).
  3. Store switcher (Ctrl+K) works; each store's accent color tints its context.
  4. All listed signature components exist in a /components/ui library with a demo/storybook route.
  5. Zero native browser dialogs anywhere.

Suggested AI prompt.

"You are building V1 of OrderFlow, a Tauri 2 desktop app for e-commerce operations. Attached is SYSTEM_DESIGN.md; follow its §2 stack, §4 schema (stores, store_settings, wallets only), §13 design system, and §14 layout exactly. Deliver: project scaffold, Rust sqlx SQLite layer with migrations, store CRUD via IPC, the sidebar shell with store switcher and Ctrl+K palette, and the reusable component library (ShimmerButton, BorderBeamCard, NumberTicker, StatusPill, AnimatedList, GlassDialog, Toast, EmptyState) with a demo route. Dark theme only. No em dashes in copy. End state: I can create, edit, and archive stores, and everything persists."

Version 2: Intake

Orders domain + Shopify sync

Goal. Orders exist. They arrive automatically from Shopify or manually, and land in a beautiful pipeline view in the NEW/CONFIRMING states.

Scope.

  • Full orders table + order_events audit trail + sync_state (§4).
  • Order state machine skeleton in Rust: all states defined, but only NEW → CONFIRMING auto-transition active; other transitions stubbed to reject.
  • Shopify connection UI in Store Settings: domain + Admin API token input, "Test connection" with animated success/failure feedback, token encrypted via OS keychain.
  • Rust polling scheduler (60s, configurable): pulls open orders, maps them (customer phone → E.164, COD vs prepaid detection from payment gateway, store defaults for delivery fee and fee payer), dedupes by shopify_order_id.
  • order:new Tauri event → toast with order summary.
  • Manual "New Order" modal (name, phone, address, city, items builder, amounts, payment method, fee payer override).
  • Orders page: pipeline board (columns per state, only NEW/CONFIRMING populated) with a table view toggle; order detail drawer showing items, customer, money breakdown, and event timeline.

Acceptance criteria.

  1. Connecting a real Shopify dev store pulls its open orders within one poll cycle.
  2. Sync survives offline periods and resumes; errors show as an amber dot + inline banner, never crash.
  3. Manual orders enter the same pipeline.
  4. Order detail drawer shows a per-order money breakdown (subtotal, delivery fee, fee payer, total).
  5. order_events logs every state change with actor.

Suggested AI prompt.

"Building V2 of OrderFlow on top of V1. Add the orders domain per SYSTEM_DESIGN.md §4 (orders, order_events, sync_state) and §6 Shopify integration: custom-app token connection with keychain encryption, a 60s Rust polling scheduler with rate-limit backoff, and mapping rules (E.164 phones, COD detection, store defaults). Build the Orders pipeline board and detail drawer per §14, the manual order modal, and the order:new toast. Implement the state machine enum from §5 in Rust but only enable NEW→CONFIRMING for now; all transitions must be validated server-side and logged to order_events."

Version 3: Confirm

The confirmation engine (WhatsApp + calls)

Goal. The daily driver: work through new orders, message and call customers, confirm or deny, with per-store and per-order attempt settings.

Scope.

  • contact_attempts + order_contact_config tables.
  • Store settings: msg_attempts, call_attempts editable with steppers; WhatsApp message template editor with variable chips ({name}, {order_number}, {items}, {total}, {store_name}) and live preview.
  • Confirmation Queue page (§7): oldest-first cards, progress strip (messages/calls used vs allowed), single prominent next-action button.
  • WhatsApp action: opens wa.me link with filled template, logs attempt, 10s undo toast.
  • Call action: copies number, opens tel: where supported, then an outcome popover (Answered→Confirmed / Answered→Denied / No answer) that logs the attempt.
  • Attempts exhausted → card enters pulsing "decision required" state.
  • Confirm → state CONFIRMED → auto PACKAGING; prepaid orders post nothing yet (wallet comes in V6) but record confirmed_at. Deny → reason picker → DENIED, animated slide-out, appears in History.
  • Per-order override popover ("Adjust attempts for this order").
  • History tab with search and filters (state, reason, date).
  • Sidebar badge counts for the queue.

Acceptance criteria.

  1. Effective attempts always resolve per-order override → store setting.
  2. Clicking Send WhatsApp opens WhatsApp with the correct prefilled, variable-substituted message and increments the counter exactly once (undo works).
  3. An order cannot be confirmed/denied by any illegal path; Rust rejects and UI never offers it.
  4. Denied orders vanish from active pipeline but are searchable in History with their reason.
  5. Keyboard: J/K navigate queue, Enter fires primary action, C confirm, D deny.

Suggested AI prompt.

"Building V3 of OrderFlow. Implement the confirmation engine per SYSTEM_DESIGN.md §7: contact_attempts and order_contact_config tables, store-level msg/call attempt settings with a template editor (variables: name, order_number, items, total, store_name), the Confirmation Queue page with progress strips and a single next-action shimmer button, wa.me deep links with logged attempts and a 10-second undo, call outcome logging, exhausted-attempts decision state, deny-with-reason flow, per-order attempt overrides, order History with search, sidebar badges, and J/K/Enter/C/D keyboard flow. Enable state transitions CONFIRMING→CONFIRMED→PACKAGING and CONFIRMING→DENIED in the Rust state machine."

Version 4: Ship

Packaging queue + tracking + transit

Goal. Confirmed orders get packed, receive tracking IDs, and move through transit toward the destination city.

Scope.

  • Packaging queue page: checklist-style cards showing items + quantity badges, inline Tracking ID + Courier inputs (courier autocomplete from history), submit animates to IN_TRANSIT.
  • Transit board (first two kanban columns of §8): In Transit cards with days-in-transit counters (amber past threshold, threshold in store settings), "Arrived in city" action → OUT_FOR_DELIVERY (delivery outcomes come in V5; for now cards just sit in that column).
  • delivery_attempts table created (used next version).
  • Editable tracking ID and courier on the order detail drawer with event logging.
  • Stale-transit daily nudge job (§16) emitting a toast/banner.

Acceptance criteria.

  1. An order cannot leave PACKAGING without a tracking ID.
  2. Courier autocomplete suggests previously used courier names per store.
  3. Days-in-transit counters update correctly across app restarts.
  4. Full pipeline board now animates cards across NEW → CONFIRMING → PACKAGING → IN_TRANSIT → OUT_FOR_DELIVERY.

Suggested AI prompt.

"Building V4 of OrderFlow. Implement packaging and transit per SYSTEM_DESIGN.md §8: the Packaging queue with item checklists and mandatory tracking ID + courier (autocomplete from history), transitions PACKAGING→IN_TRANSIT→OUT_FOR_DELIVERY, days-in-transit counters with a configurable amber threshold and a daily stale-transit nudge job, editable tracking on the order drawer, and the delivery_attempts table (schema only, logic next version). Keep all card movements animated via Framer Motion layout transitions."

Version 5: Deliver

Delivery attempts, rejections, returns

Goal. The full real-world delivery endgame: courier attempts, customer rejections, no-response retries, and returned parcels, exactly matching the courier retry rules.

Scope.

  • Delivery board completed: OUT_FOR_DELIVERY cards show attempt pips (●●○), segmented outcome control per attempt: Delivered / Rejected / No response.
  • Logic per §5: Rejected → RETURNING immediately. No response → retry until 1 + courier_retry_limit attempts (store setting, default 2 retries), then RETURNING. Delivered → DELIVERED.
  • courier_retry_limit added to store settings UI.
  • RETURNING cards (red-tinted) with "Parcel received back" → destructive-tier dialog itemizing the money consequence (fee loss for COD, refund-minus-fee for prepaid; amounts shown but wallet transactions become real in V6, so V5 records them as pending ledger entries in a staging table or flags on the order) → RETURNED.
  • DELIVERED COD orders → AWAITING_COLLECTION state with expected collection date (delivered_at + cod_collection_lag_days, setting exposed). Prepaid delivered orders → SETTLED (flag only, wallet in V6).
  • History now includes RETURNED with return_reason; return stats visible as simple counters on the store dashboard.

Acceptance criteria.

  1. A rejection never offers retries; a no-response retries exactly courier_retry_limit times before returning.
  2. Attempt pips and logs match delivery_attempts rows one-to-one.
  3. The return confirmation dialog states the exact money consequence before the user commits, with the 1.5s destructive delay.
  4. COD vs prepaid orders route to AWAITING_COLLECTION vs SETTLED correctly.

Suggested AI prompt.

"Building V5 of OrderFlow. Complete the delivery lifecycle per SYSTEM_DESIGN.md §5 and §8: attempt logging with pips, outcomes Delivered/Rejected/No response, rejection → RETURNING immediately, no-response retries capped at 1 + courier_retry_limit (store setting, default 2), RETURNING → RETURNED via a destructive-tier GlassDialog that itemizes the exact money consequence with a 1.5s confirm delay, COD delivered → AWAITING_COLLECTION with expected collection date from cod_collection_lag_days, prepaid delivered → SETTLED. Wallet postings are stubbed as pending entries; they go live in V6."

Version 6: Money

Wallet, ledger, COD collection, recharge/withdraw

Goal. The wallet becomes real. Every money event in the system posts to an immutable ledger, and the COD collection workflow closes the loop.

Scope.

  • wallet_transactions table live; balance invariant check on launch (§4 invariants).
  • Wallet page per §9: balance hero (NumberTicker + BorderBeam + 30-day sparkline), pending-money pills (awaiting collection, in-transit value, due this month placeholder), action row, filterable animated ledger with order-chip links.
  • Wire all money events, including retroactive migration of V5's pending entries:
    • Prepaid confirmation → order_income at CONFIRMED.
    • COD collection → the "Collect" panel: AWAITING_COLLECTION orders grouped by courier, multi-select, one confirmation posts atomic order_income batch → SETTLED.
    • COD return → delivery_fee_loss. Prepaid return → refund_out (total minus delivery fee).
  • Recharge and Withdraw modals with counterparty + note; negative-balance warning dialog on withdraw.
  • Low balance threshold setting + warning event/banner.
  • Per-order mini P&L block on the order drawer (§9).
  • CSV export of the ledger by date range.

Acceptance criteria.

  1. SUM(transactions) == balance always; the launch integrity check proves it.
  2. Settling a batch of 5 COD orders posts 5 linked transactions atomically (all or none).
  3. A prepaid returned order nets the store exactly the delivery fee, verifiable in the ledger.
  4. Transactions are immutable; corrections only via adjustment with mandatory note.
  5. Every ledger row with an order link opens that order's drawer.

Suggested AI prompt.

"Building V6 of OrderFlow. Implement the wallet per SYSTEM_DESIGN.md §9 and the §4 ledger invariants: wallet_transactions with signed integer amounts, immutability, and a launch integrity check. Wire all money events: prepaid income at confirmation, the COD Collect panel grouped by courier with atomic batch settlement to SETTLED, delivery_fee_loss on COD returns, refund_out (total minus delivery fee) on prepaid returns, migrating V5's pending entries. Build the wallet page: NumberTicker balance hero with BorderBeam and sparkline, pending pills, Recharge/Withdraw modals with negative-balance warnings, filterable animated ledger with order chips, low-balance threshold alerts, per-order mini P&L, and CSV export."

Version 7: Recurring

Subscriptions & monthly payments

Goal. Monthly service costs (Shopify, Printify, Canva, etc.) are tracked per store, generate due payments, and hit the wallet.

Scope.

  • subscriptions + subscription_payments tables.
  • Subscriptions section on the Wallet page: card list with service icon, amount, billing day, next due date, monthly-burn total stat.
  • CRUD modal (name, amount, currency, billing day 1-28, icon picker, auto-deduct toggle).
  • Hourly scheduler generates due rows at period start; subscription:due event → banner.
  • Mark Paid (posts subscription_charge tx) / Skip actions; auto-deduct posts automatically on the billing day with a toast.
  • "Due this month" pending pill on the wallet now live.
  • Payment history per subscription (which months paid/skipped).

Acceptance criteria.

  1. A subscription with billing day 5 generates a due payment for each new month exactly once.
  2. Auto-deduct posts on the correct day even if the app was closed on that day (catch-up on launch).
  3. Monthly burn total equals the sum of active subscriptions and appears on the store dashboard.
  4. Ledger rows link back to the subscription.

Suggested AI prompt.

"Building V7 of OrderFlow. Implement subscriptions per SYSTEM_DESIGN.md §10: subscriptions and subscription_payments tables, CRUD with icon picker and auto-deduct toggle, an hourly scheduler that creates due payments per period with launch catch-up, Mark Paid/Skip actions posting subscription_charge wallet transactions, the due-this-month wallet pill, monthly burn stat, and per-subscription payment history. Follow the existing GlassDialog and ledger patterns."

Version 8: Ads

Advertisement tracking with hidden tax

Goal. Every ad across Meta, TikTok, Google, Snapchat is tracked with daily spend and hidden tax, feeding the wallet and (next version) profit analytics.

Scope.

  • ads + ad_spend_daily tables.
  • Ads page per §11: bento grid of ad cards (platform chip with brand colors, status pill, daily budget, tax %, 14-day sparkline, effective monthly spend).
  • Two-step Create Ad modal with live effective-cost preview ("Rs 5,000/day → Rs 5,775/day after 15.5%").
  • "Log today's spend" quick panel: all active ads, inline inputs prefilled with daily budget, one submit posts all.
  • Backfill calendar per ad showing logged/missing days.
  • Effective spend = raw × (1 + tax/100), always shown beside raw.
  • Each spend log posts an ad_spend wallet transaction.
  • Pause/end ads; ended ads stop expecting spend.
  • Optional per-day attributed-orders field → cost per order on the ad card.
  • Platform rollup donut (spend share by platform).

Acceptance criteria.

  1. Logging spend for 4 ads in the quick panel creates 4 spend rows and 4 wallet transactions atomically.
  2. A day cannot be logged twice for the same ad (unique constraint surfaces as a friendly inline error).
  3. Effective vs raw spend both visible everywhere money is shown.
  4. Pausing an ad removes it from the quick panel from that date forward; history intact.

Suggested AI prompt.

"Building V8 of OrderFlow. Implement ad tracking per SYSTEM_DESIGN.md §11: ads and ad_spend_daily tables, the bento ads grid with platform brand chips and sparklines, the two-step create modal with live effective-cost preview using hidden_tax_pct, the daily quick-log panel posting atomic ad_spend wallet transactions, a backfill calendar per ad, pause/end lifecycle, optional attributed orders with cost-per-order, and the platform spend-share donut. Effective spend (raw times 1 plus tax percent over 100) must appear beside raw spend everywhere."

Version 9: Insight

The analytics channel

Goal. All the data collected in V2-V8 becomes graphs and answers: revenue, spend, profit, funnels, return analysis, ROAS, per store and global.

Scope.

  • Analytics page per §12 with 7d/30d/90d/custom range switcher and animated chart transitions (Recharts).
  • KPI header with NumberTickers + delta arrows vs previous period: Revenue, Effective Ad Spend, Net Profit, Orders, ROAS.
  • Charts: Revenue vs Spend vs Profit hero area chart; order funnel with stage drop-off (confirmation rate, delivery success rate highlighted); return analysis by reason + fee losses over time; COD vs prepaid stacked bars; ad platform donut + sortable per-ad table; monthly wallet waterfall; top cities by orders and return rate.
  • All aggregation done in SQL through dedicated analytics::* commands (no client-side loops over raw rows).
  • Global Overview upgraded: per-store cards now live (balance, today's orders, pending confirmations, profit sparkline) plus a cross-store combined profit chart.
  • Net profit formula: settled income − effective ad spend − subscription charges − delivery fee losses − refund losses, matching the ledger exactly.

Acceptance criteria.

  1. Net profit on the analytics page equals what you can hand-compute from the ledger for the same range.
  2. Funnel percentages reflect real state history from order_events, not current states only.
  3. Range switching animates without refetch jank (cached via TanStack Query).
  4. Global overview reflects all stores and updates when the underlying data changes.

Suggested AI prompt.

"Building V9 of OrderFlow. Implement the analytics channel per SYSTEM_DESIGN.md §12: SQL-side aggregation commands, the KPI header with deltas (Revenue, Effective Spend, Net Profit, Orders, ROAS), the hero Revenue/Spend/Profit chart, the order funnel with drop-offs computed from order_events history, return analysis, COD vs prepaid mix, ad platform breakdown with a sortable table, monthly wallet waterfall, and city heat list. Upgrade the Global Overview to live cross-store bento cards with a combined profit chart. Net profit must reconcile exactly with the wallet ledger."

Version 10: Polish

Design finale, safety, and ship-readiness

Goal. Everything that turns a working app into a product you trust with your business: the full dialog/warning system, empty and error states everywhere, backups, exports, performance, and final motion polish.

Scope.

  • Complete the dialog system per §15: all four severity tiers, destructive 1.5s progress-ring delay, type-to-confirm for delete store and restore backup, consequence itemization audit across every destructive action in the app.
  • Empty states pass: every list/queue/page has a designed empty state with illustration and primary action.
  • Error states pass: sync failures, token expiry, DB issues as inline banners with retry + copy diagnostics.
  • Backups per §17: daily rotating snapshots (keep 14), manual backup/restore with type-to-confirm, VACUUM INTO.
  • Exports: orders and ad spend CSV (ledger export exists from V6) per store per range.
  • Notifications pass: COD collection reminders, stale transit, low balance, subscription due, all as a unified notification center popover in the sidebar.
  • Performance pass: virtualized lists on pipeline/ledger/history, index audit, cold start under 2 seconds.
  • Accessibility pass: focus rings, full keyboard coverage, reduced motion, AA contrast audit.
  • Final motion polish: page transitions, card physics, money pulses, settle-confetti moment when a big COD batch is collected.
  • Onboarding: first-run guided flow (create store → connect Shopify → settings walkthrough) using animated beams.

Acceptance criteria.

  1. Every destructive action in the app itemizes its consequence and cannot be triggered by a reflex click.
  2. Kill the app mid-write; relaunch shows intact data and a passing integrity check.
  3. Restore from backup works end to end with type-to-confirm.
  4. 5,000-order store scrolls at 60fps on the pipeline and ledger.
  5. A brand-new user reaches their first confirmed order guided entirely by the onboarding flow.

Suggested AI prompt.

"Building V10, the final version of OrderFlow. Execute the polish pass per SYSTEM_DESIGN.md §15-§18: complete the four-tier GlassDialog system with destructive delays and type-to-confirm, audit every destructive action for consequence itemization, designed empty and error states everywhere, rotating backups with VACUUM INTO and guarded restore, CSV exports, a unified notification center (collection reminders, stale transit, low balance, subscriptions due), list virtualization and index audit for 5,000+ orders, accessibility (focus, keyboard, reduced motion, AA contrast), final Framer Motion polish including a collection celebration moment, and a first-run onboarding flow with animated beams."

Cross-Version Rules (apply to every prompt)

  1. The design doc wins. If generated code conflicts with SYSTEM_DESIGN.md, fix the code.
  2. State machine is sacred. All order transitions validated in Rust, logged to order_events. The UI never mutates state directly.
  3. Money is integers. Minor units only. Ledger transactions are immutable. Balance always equals the sum.
  4. No native dialogs, no light theme, no em dashes in UI copy.
  5. Every new list uses AnimatedList; every new money value uses NumberTicker; every new primary action uses ShimmerButton. Consistency compounds.
  6. Each version must end runnable. Migrations are additive and numbered; never edit an old migration.
  7. Test data. Each version's prompt should also produce a seed script (seed_demo_data) so features are visible immediately without a live Shopify store.