Shared Architecture & Components Design

Date: 2026-04-15 Author: Dagan Gilat + Claude

Context

PlantagoAI operates multiple projects sharing a common technical stack. This document captures the architecture decision to extract shared components into reusable packages under the @plantagoai namespace, maximizing reuse across all active projects.

Active Projects

Note: Nomadex is already on app stores and will not be modified at this stage. FaxPulse is inactive and excluded.

Common Technical Stack

• Firebase: Auth, Firestore, RTDB, Cloud Functions (Node 22), Hosting, Storage
• Frontend: React + TypeScript + Vite (majority), Vue (Nomadex only)
• Backend: Firebase Cloud Functions (all); Anchor on-chain program for Foundation
• AI: Anthropic Claude API, Google Gemini
• Payments: Braintree (server-side), Apple Pay, Google Pay
• Messaging: Resend (transactional email), Firebase Cloud Messaging
• Blockchain: Solana (Anchor smart contracts, Foundation only)

Design Requirements

All shared components must satisfy:

• Security: Auth isolation, tenant boundaries, input validation at system edges
• Privacy: Zero PII storage where possible, encrypted at rest
• Compliance: GDPR-compatible, audit trails
• Scale: Firestore-native patterns (no single-document bottlenecks)
• Cost efficiency: Prompt caching for AI, batch operations for Firestore
• Consistency: Typed interfaces, shared error handling
• Maintainability: Single source of truth per concern
• Resiliency: Graceful degradation, retry with backoff

Shared Package Architecture

Package Namespace: @plantagoai/*

/Users/dagan/dev/shared/
  packages/
    firebase-core/     # Firebase init, Firestore helpers, env detection
    auth/              # Auth flows, role hierarchy, multi-tenant (tenant_id in claims + scoping)
    payments/          # Braintree, Apple Pay, Google Pay
    ai/                # Claude + Gemini wrappers with cost tracking
    messaging/         # Email (Resend), push (FCM), in-app notifications
  package.json         # npm workspaces root
  tsconfig.base.json   # shared TypeScript config

Projects consume packages via local file links:

"@plantagoai/auth": "file:../../shared/packages/auth"

Package Details

@plantagoai/firebase-core

Consumers: Foundation, MarketHub, Soho, HerbPulse

• Firebase app initialization with environment detection (devnet/prod/local emulator)
• Typed Firestore CRUD helpers (get, list, create, update, delete)
• Batch operation utilities (batched writes, pagination cursors)
• Tenant-scoped query builder (wraps queries with where('tenant_id', '==', ...))
• RTDB presence/status helpers
• Firestore security rules snippets (reusable .rules templates)

@plantagoai/auth

Consumers: Foundation, MarketHub, Soho, HerbPulse

• Firebase Auth wrapper: email/password, Google, Apple, biometric (WebAuthn)
• Role hierarchy system: super_admin > admin > vendor > user > demo_user
  • Foundation uses: super_admin, admin, user, demo_user
  • MarketHub adds: vendor
• Custom Claims management (set/get roles via Admin SDK)
• Multi-tenant context: tenant_id in claims and Firestore scoping
• Auth middleware for Firebase Cloud Functions (extracted from MarketHub's authMiddleware.js)
• Session management: token refresh, expiry handling
• Biometric login loop prevention (fix from Foundation)

@plantagoai/payments

Consumers: Foundation, MarketHub

• Braintree client token generation
• Payment processing (one-time + subscriptions)
• Apple Pay / Google Pay integration wrappers
• Subscription lifecycle: trial activation, billing, reminders
• Commission/payout processing (MarketHub marketplace model)
• Webhook handlers for Firebase Cloud Functions

@plantagoai/ai

Consumers: Foundation, MarketHub, Soho

• Anthropic Claude SDK wrapper with prompt caching enabled by default
• Google Gemini wrapper for vision/multimodal tasks
• Cost tracking and rate limiting per tenant
• Shared prompt templates (constitutional review, product descriptions, SEO, translations)
• Token usage logging to Firestore for billing/audit

@plantagoai/messaging

Consumers: All active projects

• Resend wrapper for transactional email
• Firebase Cloud Messaging for push notifications
• In-app notification system (Firestore collection + RTDB real-time)
• Template system with per-tenant branding
• Email templates: welcome, verification, alerts, subscription reminders

Stack Commentary

Strengths

• Firebase + Vite across all projects provides operational consistency
• Braintree in both Foundation and MarketHub is directly extractable
• MarketHub already has mature patterns: authMiddleware, setUserRole, subscription management, i18n
• Node 22 on Functions across the board
• Rust backend for Foundation's high-security/blockchain needs is the right tool

Alignment Needed

• JS vs TS: MarketHub is plain JSX; others are TypeScript. Shared packages will be TypeScript with JS-compatible exports (compiled to ESM + CJS)
• Vue vs React: Nomadex (Vue) is excluded from this phase. Service-layer packages are framework-agnostic
• MarketHub serviceAccountKey.json: Must be removed from version control (security risk)

Implementation Status (Updated 2026-04-15)

Phase 1 — Workspace + Firebase Core + Auth — COMPLETE

• Shared workspace at /Users/dagan/dev/shared/ with npm workspaces
• @plantagoai/firebase-core: env detection, Firestore CRUD, tenant-scoped queries, admin SDK
• @plantagoai/auth: ring-based permission system (Linux-style protection rings)
  • Ring 0: Platform owner | Ring 1: Tenant admin | Ring 2: Privileged | Ring 3: User | Ring 4: Restricted
  • Each project maps its own role names to ring levels via defineRoles()
  • Middleware: requireRing(), requireTenantAccess(), setUserClaims(), bootstrapPlatformOwner()
• Integrated: Foundation (frontend + functions), MarketHub (frontend + functions), Soho (web-app + admin), HerbPulse
• Both Foundation and MarketHub functions upgraded to ESM + modern Firebase SDKs

Phase 2 — Payments — COMPLETE

• @plantagoai/payments: Braintree gateway, payment processing, subscription lifecycle
• @plantagoai/payments/client: Apple Pay + Google Pay Drop-in UI (browser capability checks)
• MarketHub: 4 functions migrated to shared package (getBraintreeClientToken, processBraintreePayment, activateTrialPeriod, activateSubscription)

Phase 3 — AI + Messaging — COMPLETE

• @plantagoai/ai: Claude with prompt caching + Gemini vision, usage tracking to Firestore
• @plantagoai/messaging: Resend email + FCM push + in-app notifications
• Foundation: evaluateProposal uses claudeWithCache() for constitution review with prompt caching
• Foundation: new sendNotification Cloud Function for in-app notifications

Consumer Integration Pattern

Each project adds shared packages to its package.json:

{
  "dependencies": {
    "@plantagoai/firebase-core": "file:../../shared/packages/firebase-core",
    "@plantagoai/auth": "file:../../shared/packages/auth"
  }
}

Firebase Cloud Functions also reference shared packages:

{
  "dependencies": {
    "@plantagoai/auth": "file:../../../shared/packages/auth"
  }
}

No npm publishing required — local workspace links keep everything in sync during development.