Goal

Enable developers to connect Firebase Realtime Database or Firestore as a data source in Preswald apps by defining it in the [data] section of preswald.toml. This allows loading and visualizing cloud-hosted NoSQL data natively within a Preswald dashboard.

📌 Motivation

Many teams use Firebase (Firestore or Realtime DB) to store analytics, user activity, IoT feeds, or configuration data. Adding native Firebase support will:

• Extend Preswald’s reach to modern cloud-first apps
• Simplify workflows for front-end and mobile-first dev teams
• Enable real-time dashboards from Firebase sources

✅ Acceptance Criteria

• Add support for type = "firebase" in [data.*] sections of preswald.toml
• Support both:
  • Firestore (default)
  • Realtime Database (optional via mode = "realtime")
• Accept required fields:
  • credentials_path: path to Firebase service account key JSON
  • project_id: Firebase project
  • collection (for Firestore) or path (for Realtime DB)
• Load data into a Pandas DataFrame in get_df()
• Validate with Firestore JSON documents and flatten nested fields
• Add error handling for auth, connectivity, and permission issues

🛠 Implementation Plan

1. Example preswald.toml Config

[data.user_metrics]
type = "firebase"
credentials_path = "secrets/firebase-key.json"
project_id = "my-firebase-project"
collection = "metrics"  # for Firestore
mode = "firestore"      # default

Or for Realtime DB:

[data.sensors]
type = "firebase"
credentials_path = "secrets/firebase-key.json"
project_id = "my-firebase-project"
path = "/devices/sensors"
mode = "realtime"

2. Backend Code

• Use firebase-admin SDK
• Add a new data loader in preswald/engine/managers/data.py:

import firebase_admin
from firebase_admin import credentials, firestore, db

def load_firebase_source(config):
    cred = credentials.Certificate(config["credentials_path"])
    firebase_admin.initialize_app(cred, {
        "projectId": config["project_id"],
        "databaseURL": f"https://{config['project_id']}.firebaseio.com"
    })

    if config.get("mode", "firestore") == "firestore":
        client = firestore.client()
        docs = client.collection(config["collection"]).stream()
        records = [doc.to_dict() for doc in docs]
    else:
        ref = db.reference(config["path"])
        records = ref.get()

    return pd.json_normalize(records)

🧪 Testing Plan

• Use public Firebase sandbox data or mock Firestore collection
• Run with:

  connect()
  df = get_df("user_metrics")
  table(df)

• Validate:
  • Nested Firebase docs are flattened correctly
  • Empty/nulls handled gracefully
  • JSON fields are not lost or truncated

📚 Docs To Update

• docs/configuration.mdx → Add type = "firebase"
• Add sample preswald.toml snippet
• Add to data source compatibility matrix

🧩 Related Files

• preswald/engine/managers/data.py
• preswald.toml
• secrets.toml
• Dependencies:
  • firebase-admin (pip install firebase-admin)

🔮 Future Ideas

• Support real-time data sync (via polling or websocket)
• Allow Firebase auth via token (instead of service account)
• Allow subcollection expansion and document filtering