QUICKBOOKS INTEGRATION PLAN

/cl# SmartCrew → QuickBooks Integration Plan

Executive Summary

This document outlines a high-level integration plan for syncing SmartCrew Admin Console data with QuickBooks Online for comprehensive accounting management. The integration will leverage Firebase Cloud Functions for secure API key management and the node-quickbooks NPM package for API interactions.

Architecture Overview

Security Architecture

API Key Storage: QuickBooks API credentials stored securely in Firebase Cloud Functions environment variables
Authentication Flow: OAuth 2.0 handled server-side via Cloud Functions
Client Communication: Flutter web app communicates with Cloud Functions, never directly with QuickBooks
Data Flow: SmartCrew → Cloud Functions → QuickBooks API

Technology Stack

Backend: Firebase Cloud Functions (TypeScript)
QuickBooks SDK: node-quickbooks NPM package
Frontend: Flutter Web (existing SmartCrew Admin Console)
Database: Firestore (existing)

Data Mapping: SmartCrew → QuickBooks

1. Company & Organization

SmartCrew Entity: Company QuickBooks Entity: CompanyInfo Mappable Fields:

Company.name → CompanyInfo.CompanyName
Company.startTime/endTime → Business hours configuration
Company.id → External reference tracking

2. Customers

SmartCrew Entity: CustomerBasic QuickBooks Entity: Customer Mappable Fields:

companyName → DisplayName
contactPerson → GivenName/FamilyName
email → PrimaryEmailAddr.Address
phoneNumber → PrimaryPhone.FreeFormNumber
address → BillAddr/ShipAddr
website → WebAddr.URI

Use Cases:

Sync all SmartCrew customers as QuickBooks customers
Enable invoice generation for projects
Track customer balances and payments

3. Vendors/Suppliers

SmartCrew Entity: Vendor QuickBooks Entity: Vendor Mappable Fields:

companyName → DisplayName
contactPerson → GivenName/FamilyName
email → PrimaryEmailAddr.Address
phoneNumber → PrimaryPhone.FreeFormNumber
address → BillAddr
vendorType → Custom field/Notes
paymentTerms → TermRef

Use Cases:

Sync material suppliers and equipment vendors
Track vendor bills and payments
Manage 1099 contractor information

4. Employees & Labor

SmartCrew Entity: AppUser + Labor QuickBooks Entities: Employee + TimeActivity Mappable Fields:

Employee Creation:

firstName + lastName → DisplayName
email → PrimaryEmailAddr.Address
phoneNumber → PrimaryPhone.FreeFormNumber
hourRate → HourlyRate (for hourly employees)
role → Title
active → Active status

Time Tracking:

DailyLog.clockIn/clockOut → TimeActivity.StartTime/EndTime
JobsiteActivity → TimeActivity.Description
Project reference → TimeActivity.CustomerRef
Labor hours → TimeActivity.Hours
Billable status → TimeActivity.Billable

Use Cases:

Sync all employees for payroll processing
Import daily time logs as TimeActivity records
Track billable vs non-billable hours
Generate payroll reports

5. Projects

SmartCrew Entity: Project QuickBooks Entities: Customer:Job (sub-customer) + Class Mappable Fields:

projectName → Customer.DisplayName (as sub-customer)
clientId → ParentRef (link to main customer)
expectedRevenue → Custom field for tracking
laborBudget → Budget tracking
materialBudget → Budget tracking
machineBudget → Budget tracking
startDate/endDate → Project timeline tracking

Use Cases:

Create projects as sub-customers under main clients
Use Classes for project categorization
Track project profitability
Monitor budget vs actual costs

6. Materials & Inventory

SmartCrew Entity: Materials QuickBooks Entities: Item (Service/NonInventory) + Bill or Purchase Mappable Fields:

item → Item.Name
vendorName → VendorRef
quantity → Qty
cost → UnitPrice
project → CustomerRef (for job costing)
billable → Item.Type (billable vs non-billable)
className → Class tracking

Use Cases:

Create items for frequently used materials
Record material purchases as Bills or Purchases
Track material costs per project
Generate material usage reports

7. Equipment

SmartCrew Entity: Equipment + EquipmentServiceRecord QuickBooks Entities: Item (Service type for rental rates) + FixedAsset + Purchase Mappable Fields:

name → Item.Name / FixedAsset.Name
hourRate → Item.UnitPrice (for equipment rental rates)
price → FixedAsset.PurchaseCost
purchaseDate → FixedAsset.PurchaseDate
Service records → Purchase/Bill for maintenance

Use Cases:

Track equipment as fixed assets
Bill equipment usage to projects
Record maintenance expenses
Calculate equipment depreciation

8. Financial Transactions

Invoicing

SmartCrew → QuickBooks Invoice:

Project completion → Generate Invoice
Customer reference → Invoice.CustomerRef
Labor hours × rates → Invoice.Line (Service items)
Materials (billable) → Invoice.Line (Product items)
Equipment usage → Invoice.Line (Service items)

Expense Tracking

SmartCrew → QuickBooks Bill/Purchase:

Material purchases → Bill (with VendorRef)
Equipment maintenance → Purchase
Other project expenses → Purchase/Bill with Class tracking

Payroll Integration

SmartCrew → QuickBooks Payroll:

TimeActivity records → Payroll hours
Employee rates → Payroll calculations
Overtime calculations → Based on SmartCrew overtime rules

9. Reporting Integration

Reports to Generate in QuickBooks:

Project Profitability (P&L by Class/Customer)
Labor Cost Reports (Time by Customer)
Material Usage Reports (Expenses by Customer)
Vendor Payment Reports (A/P Aging)
Customer Invoice Reports (A/R Aging)
Cash Flow Statements
Budget vs Actual (by Project/Class)

Sync Strategy

Real-time Sync Triggers

Customer/Vendor Changes: Immediate sync on create/update
Employee Changes: Immediate sync for active status changes
Invoice Generation: Sync when project milestones are reached

Batch Sync Operations

Daily Time Logs: End-of-day batch sync
Material Purchases: Daily batch sync
Equipment Usage: Weekly sync
Project Updates: Daily sync for active projects

Conflict Resolution

Master Data Source: SmartCrew remains source of truth
Update Direction: One-way sync (SmartCrew → QuickBooks)
Error Handling: Failed syncs queued for retry
Audit Trail: Log all sync operations in Firestore

Cloud Functions Implementation

Required Cloud Functions

// Authentication
- initializeQuickBooksAuth()
- refreshQuickBooksToken()

// Customer Management
- syncCustomerToQuickBooks()
- batchSyncCustomers()

// Vendor Management
- syncVendorToQuickBooks()
- batchSyncVendors()

// Employee & Time Tracking
- syncEmployeeToQuickBooks()
- syncTimeActivityToQuickBooks()
- batchSyncDailyLogs()

// Project Management
- createProjectInQuickBooks()
- updateProjectBudgets()

// Financial Transactions
- createInvoiceFromProject()
- recordMaterialPurchase()
- recordEquipmentUsage()

// Reporting
- generateProjectProfitabilityReport()
- generatePayrollReport()
- generateCashFlowStatement()

Environment Variables Required

QB_CLIENT_ID=<QuickBooks App Client ID>
QB_CLIENT_SECRET=<QuickBooks App Client Secret>
QB_REDIRECT_URI=<OAuth Redirect URI>
QB_ENVIRONMENT=<sandbox|production>
QB_WEBHOOK_TOKEN=<Webhook Verification Token>

Data Validation & Mapping Rules

Customer/Vendor Validation

Ensure unique DisplayName in QuickBooks
Map SmartCrew ID to QuickBooks ExternalId
Validate email and phone formats

Time Entry Rules

Round time to nearest 15 minutes (configurable)
Apply overtime rules from SmartCrew
Validate against QuickBooks payroll periods

Invoice Generation Rules

Group labor by employee and rate
Apply project markup percentages
Include only billable materials
Add equipment usage as line items

Benefits & Business Value

Immediate Benefits

Automated Bookkeeping: Eliminate manual data entry
Real-time Financial Visibility: Current project profitability
Streamlined Payroll: Direct time entry to payroll system
Accurate Job Costing: Track all project expenses
Simplified Tax Preparation: All data in QuickBooks

Long-term Benefits

Better Cash Flow Management: Real-time A/R and A/P tracking
Improved Profitability Analysis: Detailed project margins
Compliance: Proper books for audits and taxes
Scalability: Handle growing transaction volumes
Integration Ecosystem: Connect with other QuickBooks integrations

Limitations & Considerations

QuickBooks API Limitations

Rate Limits: 500 requests/minute, 500K/month for Builder tier
Batch Size: Maximum 30 operations per batch request
Data Retention: Deleted records retained for 30 days only
Custom Fields: Limited custom field support

Data Synchronization Challenges

Schema Differences: Not all SmartCrew fields map directly
Business Rule Conflicts: QuickBooks may reject certain data
Timing Issues: Payroll period vs SmartCrew log dates
Currency Handling: Ensure consistent currency codes

Recommended Phased Approach

Phase 1: Core Entities (Month 1)

Customers and Vendors sync
Basic employee sync

Phase 2: Time Tracking (Month 2)

Daily log to TimeActivity sync
Basic payroll integration

Phase 3: Project Financials (Month 3)

Project creation and tracking
Material and equipment cost tracking

Phase 4: Invoicing & Reporting (Month 4)

Automated invoice generation
Financial reporting integration

Next Steps

Obtain QuickBooks Developer Account: Register app in QuickBooks
Set Up Sandbox Environment: Test integration safely
Implement OAuth Flow: Secure authentication in Cloud Functions
Create Data Mapping Service: Build transformation layer
Develop Sync Queue System: Handle batch operations
Build Error Recovery: Implement retry logic and notifications
Create Admin UI: Add QuickBooks sync controls to SmartCrew
Test with Pilot Customer: Validate with real data
Document User Workflows: Train users on new features
Monitor and Optimize: Track sync performance and errors

Conclusion

This integration will transform SmartCrew from a project management tool into a comprehensive business management platform. By leveraging QuickBooks' robust accounting features while maintaining SmartCrew's specialized construction management capabilities, businesses can operate more efficiently with real-time financial insights and automated bookkeeping processes.

QUICKBOOKS INTEGRATION PLAN

On this page