Pivot POS Service Specification
Status: Draft
Last Updated: December 2025 Related Documents: POS Integration Strategy
Overview
This specification defines a standalone POS integration service that operates independently from the main Pivot Firebase infrastructure. The service is built on:
- Cloud Run for compute (replacing Firebase Functions)
- BigQuery for data storage (replacing Firebase Realtime Database)
- Cloud Scheduler for periodic sync jobs
- TypeScript/Node.js as the runtime
This architecture mirrors the existing pivot-docs and pivot-kpi services, providing a battle-tested deployment pattern.
Why a Separate Service?
| Concern | Firebase Functions | Cloud Run Service |
|---|---|---|
| Cold Start | 3-10 seconds | <1 second (min instances) |
| Execution Limit | 9 minutes max | 60 minutes max |
| Memory | 8GB max | 32GB max |
| Concurrency | 1 per instance | 80+ per instance |
| Cost at Scale | Per invocation | Per CPU-second |
| Deployment | Coupled to Firebase | Independent CI/CD |
| Database | Firebase RTDB (NoSQL) | BigQuery (Analytics-optimized) |
POS integrations require:
- Long-running data syncs (historical backfills)
- High write volume, infrequent reads
- Analytics-friendly query patterns
- Independent scaling from main app
Document Structure
For Product/Business Stakeholders
- Overview - Business case, goals, success metrics
For Technical Team
- Architecture - Cloud Run + BigQuery design
- Data Model - BigQuery schema and data flows
- Toast Integration - Toast-specific implementation
Quick Reference
Service Name: pivot-pos-service
Port: 7492 (dev)
Repository: pivot-meta/pivot-pos (new)
Terraform: pivot-devops/infrastructure/dev/pivot-pos/
Endpoints:
POST /sync/toast/:companyId - Trigger Toast sync for company
GET /health - Health check
POST /webhooks/toast - Toast webhook receiver (future)
Cloud Scheduler Jobs:
pivot-pos-sync-hourly - Sync all active POS integrations
Architecture Diagram
Implementation Phases
Phase 1: Foundation
- Cloud Run service with Express/Fastify
- BigQuery schema and initial tables
- Toast authentication implementation
- Basic sync for employee roster
Phase 2: Core Data
- Time clock sync (in/out punches)
- Sales per employee
- Tips per employee
- Incremental sync with timestamps
Phase 3: Production Hardening
- Cloud Scheduler integration
- Error handling and retries
- Alerting and monitoring
- Historical backfill support
Phase 4: Additional POS Systems
- Square integration
- Clover integration
- Silverware integration
Decision Log
| Decision | Choice | Rationale |
|---|---|---|
| Storage | BigQuery over PostgreSQL | Analytics-optimized, serverless, cost-effective for write-heavy/read-light workloads |
| Compute | Cloud Run over Cloud Functions | Longer execution, better cold starts, independent deployment |
| Language | TypeScript | Team familiarity, type safety, matches pivot-kpi |
| Framework | Express.js | Simplicity, ecosystem, matches existing services |