feat: add Spice N'Vybe client project files
- SOW v2.0 PDF (client scope document) - Meeting prep for July 4 Kay alignment - M01 BI dashboard architecture spec - API data source research (QBO, Plaid, SpotOn) - Project README with structure overview
This commit is contained in:
@@ -0,0 +1,140 @@
|
||||
# Kay Meeting Prep — Spice N'Vybe Alignment
|
||||
**Date:** July 4, 2026
|
||||
**Purpose:** Align on scope, priorities, and data access — not a sales pitch
|
||||
**Reference:** SNV_AI_Scope_of_Work_v2.pdf (client's signed SOW)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Meeting Approach
|
||||
|
||||
**Tone: Discovery + Alignment, not a demo or sales pitch.**
|
||||
|
||||
We've reviewed their SOW in full. We didn't build it, so we're not showing them a dashboard they haven't seen yet. Instead, we're figuring out what they actually need so we can start building what matters.
|
||||
|
||||
> *"Kay, we've reviewed your SOW in detail. A few things we want to nail down so we can start building immediately."*
|
||||
|
||||
---
|
||||
|
||||
## ❓ Key Questions for Kay (in Priority Order)
|
||||
|
||||
### 1. What's the ONE thing you need working first?
|
||||
|
||||
The SOW sequences the Dashboard (M01) last in Weeks 11-14, after everything else. Is that still your priority order, or has that changed?
|
||||
|
||||
**Probe options if he's unsure:**
|
||||
- Dashboard with real financial data?
|
||||
- Chatbot for the Cloud Kitchen team to look up SOPs/menus?
|
||||
- Training system you mentioned already has a foundation?
|
||||
- CRE listings coming in automatically?
|
||||
|
||||
**Our recommendation (if he asks):**
|
||||
> *"The fastest path to value is getting the Dashboard live with just one data source — SpotOn sales data. That gives you real numbers in 2-3 weeks. We layer on Plaid, QBO, and everything else after."*
|
||||
|
||||
### 2. MarginEdge — do you use it?
|
||||
|
||||
It's referenced in M01, M02, and M03. If they use it, we need API access to scope integration. If they don't, we drop it.
|
||||
|
||||
### 3. Gmail + Google Calendar in the Dashboard — critical or nice-to-have?
|
||||
|
||||
The SOW mentions unanswered email queue and a calendar widget. Find out: is this MVP, v1.1, or not pressing?
|
||||
|
||||
### 4. Existing Training System — what's there?
|
||||
|
||||
SOW says M06 *"extends the existing kitchen training system already in operation"*. We need to see what they have before we scope.
|
||||
|
||||
### 5. CRE Scraper — how do you want to handle it?
|
||||
|
||||
Loopnet/Crexi scraping is legally grey. Do they accept a browser-automation approach, or do they prefer a paid data feed?
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Critical Unlocks (Need These to Start)
|
||||
|
||||
| # | Item | Who's responsible | Status ⬜ |
|
||||
|---|---|---|---|
|
||||
| 1 | **SpotOn API keys** — Oakland Park + Ft. Lauderdale | Kay | ⬜ |
|
||||
| 2 | **QBO OAuth access** — realm ID, Intuit dev account | Kay | ⬜ |
|
||||
| 3 | **Plaid credentials** — client_id + secret, or Link flow | Kay | ⬜ |
|
||||
| 4 | MarginEdge — yes/no? If yes, account access | Kay | ⬜ |
|
||||
| 5 | Gmail API — needed for M01? | Kay | ⬜ |
|
||||
| 6 | Google Calendar API — needed for M01? | Kay | ⬜ |
|
||||
| 7 | M06 existing training system — can we see it? | Kay | ⬜ |
|
||||
|
||||
> **Pitch if hesitating:** *"The single biggest unlock is data access. If we can get SpotOn, QBO, and Plaid credentials this week, we can have a live prototype running in 2-3 weeks."*
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ Our Real Delivery Priority (Not the SOW's Sequence)
|
||||
|
||||
| Phase | What | Why |
|
||||
|---|---|---|
|
||||
| **Week 1** | Get API keys | Everything blocks on this |
|
||||
| **Weeks 2-4** | M01 core dashboard (SpotOn sales first) | Fastest visible win — real numbers |
|
||||
| **Weeks 4-6** | M01 + Plaid + QBO | Full financial picture |
|
||||
| **Weeks 6-10** | M05 Chatbot (RAG) | Quick win — we have the inference infra |
|
||||
| **After** | M02, M03, M04, M06, M07 | Based on what Kay prioritizes |
|
||||
|
||||
**Key truth:** Don't build M01 last. A live prototype with real data in 3 weeks builds more trust than a 16-week timeline.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Conversation Flow
|
||||
|
||||
### 1. Opening — Set the Frame (2 min)
|
||||
> *"Hey Kay, thanks for the time. We've gone through your SOW thoroughly. I want to make sure we're building what actually moves the needle for you, so I've got a few questions to align on before we start."*
|
||||
|
||||
### 2. What's Priority #1? (5 min)
|
||||
> *"Your SOW sequences the Dashboard last. Is that still the plan, or has the urgency shifted?"*
|
||||
|
||||
Let him talk. Listen for what he *actually* cares about.
|
||||
|
||||
### 3. Data Source Check (5 min)
|
||||
> *"To build anything, we need access to your data. Let me run through what we'll need..."*
|
||||
|
||||
Go through the **Critical Unlocks** checklist above.
|
||||
|
||||
Key framing:
|
||||
> *"For QuickBooks — read-only access to invoices, P&L, and payables. For banking — Plaid is view-only, we can never move money. For SpotOn — sales and labor data only."*
|
||||
|
||||
### 4. Scope Clarifiers (5 min)
|
||||
> *"A few quick clarifiers from the SOW..."*
|
||||
|
||||
- MarginEdge?
|
||||
- Gmail/Calendar in Dashboard — critical or nice-to-have?
|
||||
- Training system — can I see the current version?
|
||||
- CRE scraper — how do you want us to handle the legal side?
|
||||
|
||||
### 5. Close — Next Steps (3 min)
|
||||
> *"Once we have those API keys, I can have a working prototype with your real data in 2-3 weeks. How does that timeline feel to you?"*
|
||||
|
||||
**Confirm:**
|
||||
- Who's the point of contact for each data source
|
||||
- Tentative ETA for credentials
|
||||
- When to follow up
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Potential Objections & Responses
|
||||
|
||||
| Objection | Response |
|
||||
|---|---|
|
||||
| *"The SOW already says all this — why are we rehashing it?"* | "We're not rehashing — we're confirming. The SOW sequences things one way. I want to make sure that order still works for you before we invest time building." |
|
||||
| *"I'm not comfortable giving bank access."* | "Plaid is read-only — can see balances and transactions, never touch money. Same tech QuickBooks and Venmo use." |
|
||||
| *"I need everything at once, not phased."* | "I can build faster by starting with what matters most and adding layers. A live dashboard with sales data in 3 weeks is more useful than a complete plan in 3 months." |
|
||||
| *"Who sees our data?"* | "Stays on our private infrastructure. No third parties, no cloud sharing." |
|
||||
|
||||
---
|
||||
|
||||
## 📝 After the Meeting — Capture
|
||||
|
||||
Come back and tell me:
|
||||
|
||||
1. **Kay's priority #1** — what does he want first?
|
||||
2. **API keys** — which did he commit to? When?
|
||||
3. **MarginEdge** — yes/no?
|
||||
4. **Gmail/Calendar** — must-have or optional?
|
||||
5. **M06 training system** — what exists?
|
||||
6. **CRE scraping** — his stance?
|
||||
7. **Timeline** — what did you both agree on?
|
||||
|
||||
I'll update the project plan and start building as soon as credentials land. 🦅
|
||||
@@ -0,0 +1,37 @@
|
||||
# Spice N'Vybe — Gonzague Foods LLC
|
||||
|
||||
**Client:** Spice N'Vybe (Gonzague Foods LLC, Oakland Park, FL)
|
||||
**Contact:** Kay (Co-owner)
|
||||
**Engagement:** AI Technology Transformation — 7 Modules
|
||||
**Status:** Discovery Phase → Pending alignment meeting (July 4, 2026)
|
||||
|
||||
## Project Structure
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `SNV_AI_Scope_of_Work_v2.pdf` | Client's signed SOW — 7 AI modules, 22 pages |
|
||||
| `MEETING_PREP_KAY.md` | Pre-meeting plan for July 4 alignment meeting |
|
||||
| `architecture/m01-bi-dashboard.md` | M01 architecture spec (SpotOn, Plaid, QBO, PostgreSQL) |
|
||||
| `research/api-data-sources.md` | API research for QBO, Plaid, SpotOn integrations |
|
||||
|
||||
## The 7 Modules
|
||||
|
||||
1. **M01** — GF Unified BI Dashboard (6-8 wks)
|
||||
2. **M02** — 24-Month Financial Forecasting (4-6 wks)
|
||||
3. **M03** — AI Schedule Optimizer (4-5 wks)
|
||||
4. **M04** — CRE Intelligence Tool (3-4 wks)
|
||||
5. **M05** — Operations Chatbot (4-5 wks)
|
||||
6. **M06** — Food Prep Training System (3-4 wks)
|
||||
7. **M07** — Investor Research Engine (3-4 wks)
|
||||
|
||||
## Key Documents
|
||||
|
||||
- SOW v2.0 — full client scope
|
||||
- Meeting prep for Kay alignment (July 4, 2026)
|
||||
- M01 architecture spec (our deliverable design)
|
||||
- API data source research
|
||||
|
||||
## Delivery Approach
|
||||
|
||||
Syslog-led. Kay sets the *what*, we own the *how* and *when*.
|
||||
Fastest path: M01 Dashboard (SpotOn-first) in 2-3 weeks → iterate from there.
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,255 @@
|
||||
# Spice N'Vybe BI Dashboard — API Data Source Research
|
||||
|
||||
**Context:** Restaurant with 2 locations (Oakland Park flagship + Fort Lauderdale Cloud Kitchen). Need a BI Dashboard for Sales, Net Profit, and Costs.
|
||||
|
||||
---
|
||||
|
||||
## 1. QuickBooks Online (Accounting)
|
||||
|
||||
### Auth Method
|
||||
- **OAuth 2.0** (Authorization Code flow exclusively)
|
||||
- Two primary scopes:
|
||||
- `com.intuit.quickbooks.accounting` — full read/write to accounting data
|
||||
- `com.intuit.quickbooks.payment` — QuickBooks Payments processing
|
||||
- **Access tokens:** expire in 1 hour
|
||||
- **Refresh tokens:** rotate every 24-26 hours, max lifetime 5 years. **Critical:** you must always store and use the *latest* refresh token — reusing a rotated one revokes the entire authorization chain.
|
||||
|
||||
### Base URLs
|
||||
- Production: `https://quickbooks.api.intuit.com/v3/company/{realmId}/`
|
||||
- Sandbox: `https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}/`
|
||||
|
||||
### Available Endpoints / Entities
|
||||
|
||||
**Financial Reports (Reports API)** — most relevant for BI:
|
||||
| Endpoint | What it returns | BI Relevance |
|
||||
|---|---|---|
|
||||
| `ProfitAndLoss` | Income, COGS, Expenses, Net Income | **Core for Net Profit calculation** |
|
||||
| `BalanceSheet` | Assets, Liabilities, Equity snapshot | Treasury health |
|
||||
| `CashFlow` | Operating/Investing/Financing cash flows | Cash position |
|
||||
| `AgedReceivables` | Outstanding customer invoices | AR tracking |
|
||||
| `AgedPayables` | Outstanding bills/vendor payments | AP tracking |
|
||||
| `TrialBalance` | Full chart of accounts summary | Audit/completeness |
|
||||
|
||||
**Transactional Entities (CRUD via Query API):**
|
||||
- `Invoice` — customer invoices, line items, amounts, dates
|
||||
- `Customer` — customer profiles
|
||||
- `Payment` — received payments
|
||||
- `Bill` — vendor bills
|
||||
- `Purchase` — purchases (check, credit card, cash)
|
||||
- `PurchaseOrder` — vendor POs
|
||||
- `Vendor` — vendor profiles
|
||||
- `Account` — chart of accounts
|
||||
- `JournalEntry` — manual debit/credit entries
|
||||
- `Deposit` — bank deposits
|
||||
- `Transfer` — fund transfers between accounts
|
||||
|
||||
**Query syntax:** SQL-like — `SELECT * FROM Invoice WHERE TxnDate > '2026-01-01'`
|
||||
|
||||
### Sync Mechanism
|
||||
- **Change Data Capture (CDC)** — returns only changed records since a timestamp. **Use this** instead of polling full datasets.
|
||||
- **Webhooks** — event-driven notifications for entity changes.
|
||||
|
||||
### Rate Limits
|
||||
- **500 requests/minute per company (realmId)**
|
||||
- **10 concurrent requests per company**
|
||||
- Batch endpoint: 120 requests/minute per company
|
||||
|
||||
### BI Relevance for Sales / Net Profit / Costs
|
||||
- **Net Profit** → Pull `ProfitAndLoss` report (Income - COGS - Expenses = Net Income)
|
||||
- **Costs** → Pull `ProfitAndLoss` for expense line items; `Bill`/`Purchase` entities for granular vendor spend
|
||||
- **Sales** → Pull `ProfitAndLoss` revenue lines; **but SpotOn is better for daily/weekly sales granularity**
|
||||
- **AR/AP** → `AgedReceivables`/`AgedPayables` reports
|
||||
|
||||
> **Recommendation:** Pull QBO reports daily (or on-demand) for the P&L view. Use it as the **source of truth for net profit**, reconciling against SpotOn and Plaid data. The 1-hour access token and per-company rate limits mean you'll need a queued background worker.
|
||||
|
||||
---
|
||||
|
||||
## 2. Plaid (Banking)
|
||||
|
||||
### Auth Method
|
||||
- **API Key-based** (client_id + secret from Plaid Dashboard)
|
||||
- Sent as `PLAID-CLIENT-ID` and `PLAID-SECRET` headers, or in request body
|
||||
- **User Linking Flow:** Plaid Link widget generates an `access_token` scoped to the user's financial accounts at their institution
|
||||
- All requests are `POST` with JSON bodies
|
||||
|
||||
### Base URLs
|
||||
- Sandbox: `https://sandbox.plaid.com`
|
||||
- Production: `https://production.plaid.com`
|
||||
|
||||
### Available Products / Data Categories
|
||||
|
||||
| Product | Endpoints | Data Provided | BI Relevance |
|
||||
|---|---|---|---|
|
||||
| **Transactions** | `/transactions/sync`, `/transactions/get`, `/transactions/recurring/get`, `/transactions/refresh` | Up to **24 months** of categorized transactions; merchant names, amounts, dates, categories (PFC v1 or v2 taxonomy), geolocation | **Core for cash flow analysis**, expense categorization |
|
||||
| **Balance** | `/accounts/balance/get` | Real-time current & available balances | Working capital monitoring |
|
||||
| **Auth** | `/auth/get` | Account & routing numbers | (Low BI relevance) |
|
||||
| **Identity** | `/identity/get` | Account holder name, addresses, emails | (Low BI relevance) |
|
||||
| **Income** | `/credit/income/get` | Income streams, paystub data | Revenue verification |
|
||||
| **Investments** | `/investments/transactions/get` | Holdings and trades | (Low relevance unless they have investment accounts) |
|
||||
| **Liabilities** | `/liabilities/get` | Credit cards, student loans, mortgages | Debt tracking |
|
||||
| **Enrich** | Transaction category enrichment | Cleans raw bank descriptions with category metadata | Better expense categorization |
|
||||
| **Assets** | `/asset_report/create` | Point-in-time financial snapshot | (Optional) |
|
||||
|
||||
### Transaction Data Shape (key fields)
|
||||
```json
|
||||
{
|
||||
"transaction_id": "...",
|
||||
"account_id": "...",
|
||||
"amount": -45.50,
|
||||
"iso_currency_code": "USD",
|
||||
"date": "2026-06-15",
|
||||
"name": "US Foods Inc",
|
||||
"merchant_name": "US Foods",
|
||||
"payment_channel": "in store",
|
||||
"pending": false,
|
||||
"category": ["Food and Drink", "Restaurants"],
|
||||
"personal_finance_category": {
|
||||
"detailed": "FOOD_AND_DRINK_RESTAURANTS"
|
||||
},
|
||||
"location": {...}
|
||||
}
|
||||
```
|
||||
|
||||
### Sync Mechanism
|
||||
- **`/transactions/sync`** (preferred) — cursor-based incremental sync. Track `next_cursor` for paginated updates.
|
||||
- **`/transactions/get`** — older full-fetch approach (deprecated in favor of sync)
|
||||
- **Webhooks:** `SYNC_UPDATES_AVAILABLE`, `INITIAL_UPDATE`, `HISTORICAL_UPDATE`, `DEFAULT_UPDATE`, `TRANSACTIONS_REMOVED`
|
||||
- Plaid checks for new transactions 1-4 times per day per institution
|
||||
|
||||
### Rate Limits
|
||||
- Not explicitly documented as fixed caps per minute; they use per-request pricing tiers
|
||||
- `RATE_LIMIT_EXCEEDED` errors are a defined error type — implement retry with backoff
|
||||
- Max 500 transactions per `sync` call page; max 730 days of history
|
||||
|
||||
### Pricing
|
||||
- **Pay as You Go / Growth / Custom** tiers
|
||||
- **Transactions** is included in all tiers (one-time or per-request model)
|
||||
- Free Sandbox (200 API calls per product for initial testing)
|
||||
|
||||
### BI Relevance for Sales / Net Profit / Costs
|
||||
- **Expense categorization** → Every bank transaction has a `personal_finance_category` (e.g., `FOOD_AND_DRINK_RESTAURANTS`, `RENT_AND_UTILITIES`, `SUPPLIES`). This gives you a **real-time, categorized expense feed** that's more granular than QBO.
|
||||
- **Cash flow** → Stream daily transactions to detect revenue deposits versus vendor payments
|
||||
- **Reconciliation** → Match bank transactions against QBO records for audit-tight financials
|
||||
- **Cost monitoring** → Spot unusual vendor charges, rent payments, utility bills as they post
|
||||
|
||||
> **Recommendation:** Use Plaid Transactions sync for daily cash-flow monitoring and as a **cross-reference for costs**. The personal finance category taxonomy (PFC v2) maps well to COGS/vendor/operating expense categories. Use recurring transactions endpoint for subscription/monthly cost tracking.
|
||||
|
||||
---
|
||||
|
||||
## 3. SpotOn (POS)
|
||||
|
||||
### Auth Method
|
||||
- **API Key** — simple `x-api-key` header in each request
|
||||
- The POS Export API uses a per-location API key
|
||||
- SpotOn also provides a separate **Enterprise API** (for enterprise/venue customers) with different endpoints
|
||||
|
||||
### Base URL
|
||||
- `https://restaurantapi-qa.spoton.com/posexport/v1/` (QA environment)
|
||||
- The API is **location-centric** — all routes are scoped to `/locations/:locationId/`
|
||||
|
||||
### Available Endpoints
|
||||
|
||||
#### Transactional Endpoints
|
||||
|
||||
| Endpoint | Path | Description | BI Relevance |
|
||||
|---|---|---|---|
|
||||
| **Orders** | `GET /locations/:id/orders` | Orders with checks, payments, menu items, modifiers, tips, guests | **Core — daily sales data** |
|
||||
| **Orders (single)** | `GET /locations/:id/orders/:orderId` | Single order detail | Drill-down |
|
||||
| **Paid In/Outs** | `GET /locations/:id/paid-in-outs` | Cash paid in/out transactions (tips paid out, petty cash, deposits) | Cash management |
|
||||
|
||||
#### Reference Data Endpoints
|
||||
|
||||
| Endpoint | Path | Description | BI Relevance |
|
||||
|---|---|---|---|
|
||||
| **Menu Items** | `GET /locations/:id/menu-items` | Menu items, prices, PLU codes, report categories | Item-level sales analysis |
|
||||
| **Modifiers** | `GET /locations/:id/modifiers` | Modifier groups and options | Cost attribution |
|
||||
| **Employees** | `GET /locations/:id/employees` | Employee profiles, roles | Labor attribution |
|
||||
| **Payment Options** | `GET /locations/:id/payment-options` | Tender types (credit, cash, gift card) | Payment mix |
|
||||
| **Report Categories** | `GET /locations/:id/report-categories` | Menu categorization groups | Category-level sales |
|
||||
|
||||
#### Report Endpoints
|
||||
|
||||
| Endpoint | Path | Description | BI Relevance |
|
||||
|---|---|---|---|
|
||||
| **Labor Reports** | `GET /locations/:id/reports/labor` | Time clock entries with regular/OT pay rates, tips | **Core — labor costs** |
|
||||
| **Labor (date range)** | `GET /locations/:id/reports/labor?startDateKey=&endDateKey=` | Labor data across multiple business dates | Weekly/monthly labor |
|
||||
|
||||
### Key Order Data Shape
|
||||
Orders contain nested objects:
|
||||
- **Order** → `totalAmount`, `balanceDueAmount`, `orderTypeName`, `tableNumber`, `createdAt`, `closedAt`, `deleted`
|
||||
- **Check** → `gratuityAmount`, `totalAmount`, `paymentsAmount`, `balanceAmount`
|
||||
- **Guest** → `name`, `items[]`, `voidedItems[]`
|
||||
- **MenuItem** → `menuItemId`, `name`, `quantity`, `unitPriceAmount`, `categoryName`, `modifierGroups[]`
|
||||
- **Payment** → `amount`, `tipAmount`, `cardType`, `employeeId`
|
||||
|
||||
### Constraints
|
||||
- **Date range max:** 26 hours (can't pull more than 26h in a single orders request)
|
||||
- **History:** Only orders last updated in the last ~90 days
|
||||
- **Replication lag:** API reads from a secondary DB; 5-minute minimum lag for `updatedAtEnd` parameter
|
||||
- **Orders retrieval patterns:**
|
||||
- **Daily:** Pull last 26 hours of orders every 24 hours
|
||||
- **Near-realtime:** Poll every 5 minutes with 5-minute lag, plus a daily 26-hour catch-up
|
||||
- **Reference data:** Pull menu-items, modifiers, employees once daily; fetch individual ones on-demand
|
||||
|
||||
### Labor Report
|
||||
- Source: SpotOn's Reporting Warehouse (ETL-delayed, not real-time)
|
||||
- Returns per-employee, per-shift entries with:
|
||||
- `regularSecondsWorked`, `regularPayRateAmount`, `regularPayAmount`
|
||||
- `overtimeSecondsWorked`, `overtimePayRateAmount`, `overtimePayAmount`
|
||||
- `totalPayAmount`, `declaredCashTipsAmount`
|
||||
- `unpaidBreakSeconds`
|
||||
- **All historical data available** (not limited to 90 days like orders)
|
||||
|
||||
### Additional Note: Unofficial API
|
||||
SpotOn's official Export API is limited to reads. For **write operations** (menu updates, 86 management, reservation creation) or more comprehensive data coverage, **Supergood** offers an unofficial but production-tested API that:
|
||||
- Handles MFA/session management
|
||||
- Provides near-real-time order/payment/menu/reservation/labor data
|
||||
- Supports webhooks for async events
|
||||
- Required for two-way integration (QuickBooks sync, menu management)
|
||||
|
||||
### BI Relevance for Sales / Net Profit / Costs
|
||||
- **Sales** (by location, by item, by category) → Orders endpoint with menu items and report categories
|
||||
- **Labor costs** → Labor Reports endpoint — regular pay, overtime, tips per employee per day
|
||||
- **Payment mix** → Payment options on each check (credit vs cash vs gift card)
|
||||
- **Void/waste tracking** → voided items in order data
|
||||
- **Period comparison** → Pull orders by `closedAt` ranges for daily/weekly/monthly comparisons
|
||||
- **Costs** → SpotOn doesn't track vendor costs directly (that's QBO's domain), but paid-in-outs capture cash expenses
|
||||
|
||||
> **Recommendation:** SpotOn is your **source of truth for Sales** — daily sales by item/category/location. Labor data via the Warehouse reports gives you **labor cost %** against sales. The 26-hour window constraint means you'll need a continuous polling pattern (every 5 min during operating hours, daily catch-up).
|
||||
|
||||
---
|
||||
|
||||
## Cross-Source Integration Strategy for Spice N'Vybe BI Dashboard
|
||||
|
||||
| Metric | Primary Source | Cross-Reference | Sync Cadence |
|
||||
|---|---|---|---|
|
||||
| **Sales (daily, by location)** | SpotOn Orders | Plaid deposits (revenue matching) | Every 5 min (realtime), daily catch-up |
|
||||
| **Sales (by menu item)** | SpotOn Orders (menuItems) | — | Daily |
|
||||
| **COGS** | QuickBooks P&L | Plaid vendor payments | Daily |
|
||||
| **Labor Costs** | SpotOn Labor Reports | QuickBooks Payroll expenses | Daily |
|
||||
| **Operating Expenses** | QuickBooks P&L | Plaid transaction categories | Daily |
|
||||
| **Net Profit** | QuickBooks P&L | Aggregated from Sales - Costs | Daily (on-demand) |
|
||||
| **Cash Flow** | Plaid Transactions | QuickBooks CashFlow report | Daily |
|
||||
| **AP/AR** | QuickBooks AgedPayables / AgedReceivables | Plaid for check clearing | Daily |
|
||||
|
||||
### Data Pipeline Architecture Suggestion
|
||||
```
|
||||
SpotOn ──► (ETL: every 5min) ──► Staging DB (orders, labor, menu data)
|
||||
Plaid ──► (ETL: daily sync) ──► Staging DB (transactions, balances)
|
||||
QBO ──► (ETL: daily sync) ──► Staging DB (reports, invoices, bills)
|
||||
│
|
||||
▼
|
||||
BI Dashboard DB
|
||||
(aggregated views)
|
||||
│
|
||||
▼
|
||||
Analytics Queries
|
||||
(Sales by item, Profit by location,
|
||||
Cost trends, Cash position)
|
||||
```
|
||||
|
||||
### Key Technical Considerations
|
||||
1. **QBO OAuth token rotation requires a background worker** that refreshes tokens proactively (tokens expire in 1h, refresh tokens rotate every 24-26h)
|
||||
2. **SpotOn's 26-hour window** means you can't backfill deep history from orders — start the pipeline ASAP
|
||||
3. **Plaid's recurring transactions endpoint** (`/transactions/recurring/get`) is excellent for tracking predictable costs (rent, utilities, subscriptions)
|
||||
4. **All three APIs support webhooks** — consider event-driven architecture instead of polling where possible
|
||||
Reference in New Issue
Block a user