Profit-aware commerce intelligence for Shopify. ProfitPilot calculates true per-product profitability (COGS + the 12-18 hidden cost line items Shopify's dashboard ignores), then uses that profit data to optimize ad spend across Meta and Google, coordinates with inventory, and executes approved changes with audit trails and rollback.
This is a living document. ProfitPilot is an active SaaS project with no finish line, so this README marks what is shipped, what is scaffolded, and what is planned. It is updated as features land.
Shopify merchants optimize for revenue and ROAS while unknowingly losing money on hidden costs. Shopify's built-in analytics show revenue, not profit. The dashboard excludes actual shipping costs, return processing, per-order payment fees, ad spend allocation per product, landed COGS (freight, customs, packaging), and app overhead.
- The average Shopify store has 12-18 hidden cost line items; most merchants track fewer than half.
- Hidden fees eat 8-12% of revenue on top of COGS.
- A product can show 5x ROAS and be unprofitable after shipping, returns, and processing fees.
- Every existing ad tool optimizes for ROAS, the wrong metric. No ad tool connects to real cost data.
Merchants currently need one tool for profit tracking, one for ad management, one for inventory, and they are the integration layer — manually cross-referencing dashboards. ProfitPilot is the integration layer.
The core loop is profit -> intelligence -> recommendation -> approval -> execution -> verification:
- Ingest Shopify orders, products, refunds, and inventory via connector + webhooks.
- Calculate true per-order and per-product profit against a merchant-configured CostProfile (COGS, shipping, returns, payment fees, ad allocation).
- Analyze ad spend from Meta against true profit to compute profit-per-ad-dollar (not ROAS).
- Recommend actions: pause unprofitable ads, shift budget toward profitable products, scale winners.
- Approve recommendations in a human-in-the-loop queue. Nothing executes without consent.
- Execute approved changes through the Meta Ads API (pause/enable ad sets, adjust budgets).
- Verify post-execution impact and track savings. Roll back manually if needed.
Every step is tenant-scoped, audited, and reversible.
| Area | Status |
|---|---|
Multi-tenant auth (Shopify OAuth, Meta OAuth) with strict tenantId isolation |
Shipped |
| Tenant + workspace + CostProfile models, onboarding | Shipped |
| Shopify connector: product/order sync, webhook ingestion | Shipped |
| Profit engine: per-order + per-product true profit, leak detection, batched recalculation | Shipped |
| Ad intelligence: Meta connector (campaigns, ad sets, insights), campaign-product auto-mapping, ROAS-vs-profit view | Shipped |
| Recommendation engine: pause / shift-budget / scale, full lifecycle (draft -> approved -> executed -> verified), approval queue | Shipped |
| Execution engine: Meta ad changes (pause/enable ad sets, adjust daily budgets), manual rollback | Shipped |
| Verification service: post-execution verification + savings tracker | Shipped |
| Billing: provider-agnostic (Shopify or Polar), Free/Growth/Pro/Enterprise tiers, usage tracking, webhooks | Shipped |
| Settings: automation level, cost profile, billing management | Shipped |
| GDPR: mandatory Shopify webhooks (customers/data_request/redact) | Shipped |
| Performance: big.js financial precision, batch optimization, snapshot-first read path, Redis cache, production-safe DB indexes | Shipped |
| Area | State |
|---|---|
| LLM-assisted recommendation layer | ai (Vercel AI SDK) dependency declared; server/ai/ directory reserved. The current recommendation engine is deterministic and rules-based — a deliberate MVP choice so financial decisions are auditable. LLM augmentation is planned, not yet wired. |
| Email notifications | EMAIL_API_KEY env var declared; no notification service yet. Worker stub registered. |
| Report exports | Worker stub registered; no export service yet. |
| Area | Phase |
|---|---|
| Google Ads integration | Phase 2 |
| Shipping carrier API (ShipStation/EasyPost) — replaces manual shipping cost inputs | Phase 2 |
| Inventory-to-ads automated coordination | Phase 3 |
| Automated rollback (today: manual only) | Phase 3 |
| Agency dashboard / multi-client view | Phase 4 |
| Anonymized benchmark data (return rates, shipping norms, margin ranges) | Phase 4 |
| Admin dashboard (internal ops) | Phase 2+ |
| WooCommerce | Phase 5 |
| TikTok Ads | Phase 5 |
- Frontend: React Router 7, Shopify Polaris 13, React 18 (Shopify embedded app)
- Backend: Node.js modular monolith on the React Router server runtime
- Database: PostgreSQL 16 via Prisma 6
- Queue: BullMQ 5 + Redis 7 (ioredis) — separate worker process
- AI: Vercel AI SDK (declared, not yet wired — see status above)
- Financial precision: big.js (no floating-point money)
- Validation: Zod
- Billing: Provider-agnostic connector (Shopify or Polar)
- Testing: Vitest (unit + integration), Playwright (e2e)
- Quality: ESLint 9 (flat config), secretlint, husky + lint-staged pre-commit gates
- Security: AES-256-GCM encryption at rest for all OAuth tokens
A modular monolith with clear domain boundaries, designed to split into services later if needed.
app/ # React Router routes + UI (Polaris)
routes/ # API + page routes (profit, ads, recommendations, execution, billing, settings)
components/ hooks/ lib/ styles/
server/ # Backend domain modules
services/ # profit, ad, recommendation, execution, verification, billing, cache, gdpr, webhook
connectors/ # shopify/, meta/, billing/ (provider-agnostic)
repositories/ # Prisma data access, tenant-scoped
middleware/ config/ utils/
ai/ # reserved for LLM-assisted layer (not yet built)
prisma/ # schema.prisma + forward-only migrations
tests/ # unit/ integration/ e2e/
worker.ts # BullMQ worker entry (separate process from API)
docs/ # developer docs
Key design decisions:
- Tenant isolation is non-negotiable. Every database query includes
tenantId, enforced at the service layer. No cross-tenant access is possible. - API and workers are separate processes. The API server handles requests;
worker.tsconsumes BullMQ queues (webhooks, syncs, profit calc, recommendations, execution, verification, billing reconciliation) with graceful shutdown. - Connector pattern. Shopify, Meta, and billing are behind connector interfaces so providers can be swapped or added (Google Ads, TikTok) without touching service logic.
- Forward-only migrations. No destructive down-migrations in production. Schema changes are additive.
- Encrypted tokens. All OAuth tokens (Shopify, Meta) are AES-256-GCM encrypted at rest using
ENCRYPTION_KEY. Decrypted tokens never appear in logs or response bodies.
The project has unit, integration, and e2e test coverage. Unit tests cover profit calculations, billing, execution, verification, security, and performance helpers. Integration tests cover the cache read path, database indexes, profit performance, and recalculation progress against a dedicated test database.
Phase 1 (MVP) is feature-complete and tested. The build order so far:
- Foundation (schema, Shopify OAuth, tenancy)
- Data ingestion (Shopify connector, webhooks)
- Profit engine (per-order/per-product profit, leak report)
- Ad intelligence (Meta connector, campaign mapping, ROAS vs profit)
- Recommendations (3 types, approval queue)
- Execution (Meta ad changes, rollback)
- Verification (post-execution checks, savings tracker)
- Billing (provider-agnostic, usage tracking, webhooks)
- Billing UI (usage visibility, plan management, overage consent)
- Performance (big.js precision, batch optimization, snapshot reads, cache, indexes)
- GDPR compliance (mandatory Shopify webhooks)
Next: Google Ads and the shipping carrier API (Phase 2), then the LLM-assisted recommendation layer.
Active development. Phase 1 MVP shipped. Not production-deployed. Built as a portfolio-grade demonstration of agentic workflow architecture: multi-source data integration, real-time financial computation, approval-based execution, audit trails, and rollback.