Skip to main content

Shared Knowledge Base Architecture

Overview​

The Knowledge Base (KB) is now stored in a shared Firestore project (toto-bo) to ensure that all environments (staging and production) access the same KB entries, eliminating duplication and ensuring consistency.

Architecture​

┌─────────────────────────────────────────────────────────┐
│                    Shared KB Storage                      │
│              toto-bo Firestore (Production)              │
│              Collection: knowledge_base                  │
└─────────────────────────────────────────────────────────┘
                        ▲                    ▲
                        │                    │
        ┌───────────────┴────────┐  ┌───────┴──────────────┐
        │                         │  │                      │
┌───────▼────────┐      ┌────────▼──▼────────┐  ┌─────────▼────────┐
│  toto-ai-hub   │      │   toto-ai-hub       │  │     toto-bo      │
│   (Staging)    │      │  (Production)       │  │  (Management UI) │
└────────────────┘      └─────────────────────┘  └──────────────────┘

Key Benefits​

✅ Single Source of Truth: One KB shared across all environments
✅ No Duplication: Staging and production use the same entries
✅ Consistent Behavior: Agents behave identically across environments
✅ Centralized Management: KB managed via toto-bo UI in one place
✅ Easy Updates: Changes in toto-bo UI immediately available to all environments

Implementation Details​

1. KnowledgeBaseService​

The KnowledgeBaseService now accepts an optional sharedKbFirestore parameter:

constructor(sharedKbFirestore?: admin.firestore.Firestore)
  • If provided: Uses the shared Firestore instance (toto-bo)
  • If not provided: Falls back to default Firestore (for backward compatibility)

2. TotoAPIGateway​

The TotoAPIGateway accepts and passes the shared Firestore to KnowledgeBaseService:

constructor(sharedKbFirestore?: admin.firestore.Firestore)

3. Server Initialization​

server.js initializes toto-bo Firebase Admin SDK and passes it to the API Gateway:

const sharedKbFirestore = getTotoBoFirestore();
const apiGateway = new TotoAPIGateway(sharedKbFirestore);

Configuration​

Environment Variables​

toto-ai-hub (apphosting.yaml)​

Add the toto-bo service account secret:

env:
  - variable: TOTO_BO_SERVICE_ACCOUNT_KEY
    secret: toto-bo-service-account
    availability:
      - BUILD
      - RUNTIME

Firebase Secret Setup​

  1. Create Service Account:

    • Go to Google Cloud Console → toto-bo project
    • IAM & Admin → Service Accounts
    • Create or use existing service account for toto-ai-hub access

  2. Grant Permissions:

    • Firestore: Cloud Datastore User role
    • Read/Write access to knowledge_base collection

  3. Store Secret:

    • Download service account JSON
    • Store entire JSON as secret: toto-bo-service-account in Google Secret Manager
    • Ensure secret is accessible to toto-ai-hub App Hosting service