Building a SaaS Backend on Cloud Run + Firestore: Complete GCP Tutorial

Cloud Run + Firestore is the go-to stack for modern SaaS backends. Serverless, fully managed, and with a generous free tier, it scales from solo projects to production SaaS. This article walks through everything from multi-tenant design to billing with practical implementation examples.

Overall Architecture

Web/Mobile (React/Flutter)
        |
   Firebase Auth (authentication)
        |
   Firebase Hosting (frontend CDN) -> Cloud Run (API)
                                          |
                                          v
                              Firestore (primary DB)
                              Cloud Storage (files)
                              Pub/Sub (async processing)
                              Cloud Tasks (deferred work)
                              Stripe Webhook → Cloud Run
                              SendGrid (email)
                              Cloud Scheduler (scheduled batch)

Step 1: Firestore Multi-Tenant Design

// Structure
/tenants/{tenant_id}
  /users/{user_id}
  /subscriptions/{sub_id}
  /resources/{resource_id}

// or
/tenants/{tenant_id}/{collection}/{doc}

// Security Rules (example)
match /tenants/{tenant_id}/{document=**} {
  allow read, write: if request.auth.token.tenant_id == tenant_id;
}

Step 2: Cloud Run API (Node.js / Express)

import express from "express";
import { initializeApp, applicationDefault } from "firebase-admin/app";
import { getAuth } from "firebase-admin/auth";
import { getFirestore } from "firebase-admin/firestore";

initializeApp({ credential: applicationDefault() });
const app = express();
app.use(express.json());

// Firebase Auth verification middleware
app.use(async (req, res, next) => {
  const idToken = req.headers.authorization?.split("Bearer ")[1];
  if (!idToken) return res.status(401).send("Unauthorized");
  try {
    const decoded = await getAuth().verifyIdToken(idToken);
    req.user = decoded;
    next();
  } catch (e) {
    res.status(401).send("Invalid token");
  }
});

app.post("/api/posts", async (req, res) => {
  const db = getFirestore();
  const ref = await db.collection(`tenants/${req.user.tenant_id}/posts`).add({
    title: req.body.title,
    authorId: req.user.uid,
    createdAt: new Date(),
  });
  res.json({ id: ref.id });
});

app.listen(process.env.PORT || 8080);

Step 3: Stripe Billing Integration

import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Create the Checkout Session
app.post("/api/checkout", async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    customer_email: req.user.email,
    line_items: [{ price: "price_xxx", quantity: 1 }],
    success_url: "https://app.example.com/success",
    cancel_url: "https://app.example.com/cancel",
    client_reference_id: req.user.tenant_id,
  });
  res.json({ url: session.url });
});

// Receive the webhook
app.post("/webhooks/stripe", express.raw({ type: "application/json" }),
  async (req, res) => {
    const event = stripe.webhooks.constructEvent(
      req.body,
      req.headers["stripe-signature"]!,
      process.env.STRIPE_WEBHOOK_SECRET!
    );

    if (event.type === "checkout.session.completed") {
      const session = event.data.object;
      await getFirestore()
        .collection(`tenants/${session.client_reference_id}/subscriptions`)
        .doc("current")
        .set({ status: "active", stripeCustomerId: session.customer });
    }
    res.json({ received: true });
  }
);

Step 4: Cloud Scheduler Batch Jobs

# Cloud Scheduler -> start a Cloud Run Job
gcloud scheduler jobs create http daily-backup \
  --schedule="0 3 * * *" \
  --uri="https://my-api.run.app/jobs/backup" \
  --http-method=POST \
  --oidc-service-account-email=scheduler-sa@PROJECT.iam.gserviceaccount.com

Step 5: Firestore Backups

# Cloud Scheduler → Cloud Functions → Firestore Export
gcloud firestore export gs://my-backup-bucket/${TIMESTAMP} \
  --collection-ids=tenants

# Lifecycle rule: Archive after 90 days, delete after 365

Step 6: Monitoring and Alerting

• Cloud Monitoring SLO: 99.9% availability + P95 < 500ms
• Burn Rate Alert: fast burn (14.4x, 1h) → PagerDuty
• Cloud Logging: structured logging (jsonPayload)
• Error Reporting: automatic crash grouping
• Uptime Check: HTTP probes from 5 global regions

Pricing Example (10K MAU per month)

Best Practices

• Firebase Auth + Custom Claims (tenant_id / role)
• Enforce tenant isolation with Firestore Security Rules
• Min Instances 0 (accept cold starts to cut monthly cost)
• Set Min Instances 1+ only on critical APIs
• Manage API keys with Secret Manager
• Use Workload Identity to eliminate service account keys
• Make Stripe webhooks idempotent (dedupe by event.id)
• Pre-define Firestore composite indexes

* Google Cloud and Firebase are trademarks of Google LLC. Stripe is a trademark of Stripe, Inc.