All whitepapers

Technical Architecture

High-performance multi-tenant SaaS powered by Fastify, PostgreSQL on Neon, Google Vertex AI, and Next.js.

Core System Components

  • API Service: Fastify with Node.js and TypeScript on Google Cloud Run. Optimized for low-latency JSON routing and resilient external API integrations.
  • Database Layer: PostgreSQL hosted on serverless Neon, enforcing additive migrations, transaction isolation, and connection pooling.
  • Frontend Applications: Next.js 15 App Router, React 19, Tailwind CSS, and Shadcn UI components.
  • AI Inference: Google Vertex AI (Gemini Flash) with structured JSON output schemas, strict character limits, and graceful fallback handling.
  • Ad & Ecommerce Connectors: Direct OAuth integrations with Google Ads API, Meta Graph & Marketing APIs, TikTok Marketing API, and Shopify Admin Webhooks.

Multi-Tenancy & Security Invariants

  • Tenant Isolation: Every database query executes with an explicit organization_id filter verified by tenant middleware.
  • Authentication: Firebase Authentication validates session tokens, mapping cryptographically to internal organization roles (owner, admin, member).
  • Fail-Closed Integrations: Optional API credentials degrade gracefully without causing runtime crashes or leaking unauthenticated states.

Attribution Pipeline

  • Real-time Shopify webhook ingestion captures paid checkouts and line-item revenue.
  • UTM parameters (utm_campaign, utm_source, utm_medium) are normalized and mapped to upstream ad network entity IDs.
  • Cross-channel deduplication computes True ROAS and reports discrepancy deltas against platform self-attribution.