BizOSaaS Platform — Master Implementation Plan

---

🔒 Project Governance & Rollout Policy

[!IMPORTANT] Beta-First Strategy: To ensure platform stability and high-fidelity testing, all new features (starting with Phase 10) must follow this lifecycle:

1. Internal Alpha: Feature is restricted exclusively to [email protected].
2. Controlled Beta: Admin/Super Admin expands access to specific users/tenants via Feature Flags.
3. General Availability: Hardcoded guards are removed and feature is enabled globally.

[!TIP] Gold Standard Implementation: Every new component, service, and UI element MUST adhere to the highest architectural standards (RLS isolation, secure encryption, high-performance edge gating, and rich aesthetics).

🏗️ Unified Entitlement Engine (UEE) — The Gold Standard

To ensure robust, high-performance feature management, the platform adopts a Hierarchical Overlay Strategy:

1. Global Kill-switch: Master toggle for infrastructure-level control.
2. Alpha Guard: Hardcoded bypass for core devs (e.g. [email protected]).
3. Beta Contexts: Granular relationships to specific Users, Tenants, and Subscription Tiers.
4. Edge Gating: Decision evaluation in Next.js Middleware to minimize origin latency.

💎 Gold Standard Implementation Checklist

Every new feature MUST adhere to these architectural pillars:

• Tenant Isolation: Strict Row Level Security (RLS) on all database tables.
• Secure Vaulting: Sensitive tokens (Plaid, API keys) encrypted via AES-256-GCM.
• Background Orchestration: All ingestion/heavy lifting offloaded to BullMQ workers.
• Micro-Frontend Ready: Components themed via CSS variables (Slate for Admin, Indigo for Client).

---

Single Source of Truth. All previous planning files are archived. This is the active plan. Last Updated: 2026-04-07

---

Design Principles (User-Confirmed)

Principle	Decision
Neutral Base	Adopt the "Neutral Base + Single Brand Accent" model (Linear/ERPNext inspired)
No gradients	All UI elements use solid colors only — no from-X to-Y gradient classes
Portal distinction	Client Dashboard = Indigo/Blue primary (#2563eb). Admin Portal = Slate/Neutral primary (#334155)
Solid color scheme	Uniform accent color across all pages within each portal
Theme support	Light, Dark, System — all three modes supported
Backgrounds	Soft backgrounds (#f8fafc Light / #0f172a Dark) to reduce eye strain

---

Architecture Overview

Layer	Technology
Frontend (Client + Admin)	Next.js 15 (App Router), Tailwind, shadcn/ui
Backend API	FastAPI (Python, ai-service)
CMS / Admin Portal	Payload CMS v3 (headless)
Database	PostgreSQL (Drizzle ORM + RLS per-tenant)
Queue / Workers	BullMQ (Node.js workers) + Temporal (Python activities)
AI Orchestration	CrewAI → Payload CMS Agent Registry
AI Moderation	BizBot Sentinel (Real-time keyword/image scanning)
Deployment	Dokploy (Docker on VPS — 2vCPU / 8GB RAM)
Analytics	PostHog (session recording, funnel events)

---

Rollout Phases

✅ Phase 0 — Deployment Guard & Build Stability [COMPLETE]

• Fix broken commit b636e2129f48f3ea5121ba7c6ce62ba1b5313715
• Document Deployment Guard strategy (Dokploy rollback triggers)

✅ Phase 1 — Onboarding E2E & CRM Stability [COMPLETE]

• Playwright E2E spec: Lead → Payment → Site Provisioning → Data Sync
• PostHog funnel events: onboarding_started, payment_success, sync_completed
• CRM Kanban drag-and-drop fix and task edit persistence

✅ Phase 2 — Autonomous Health Monitoring & Self-Healing [COMPLETE]

• HealthCheckWorker (BullMQ) — pings all tenant domains every 5 min
• Self-healing: 404 detected → re-triggers Payload CMS sync + alerts Partner

✅ Phase 3 — Omnichannel Alert Management [COMPLETE]

• Reconnect Telegram/Discord connectors in ai-service
• Alert Preferences UI — channel toggles + frequency in Dashboard Settings

✅ Phase 4 — AI Concierge & Bidirectional Task Sync [COMPLETE]

• BizBot (OpenClaw) persistent interface
• syncTaskToWorkflowQueue server action — CRM tasks dispatched to external PM tools

✅ Phase 5 — 360° Business Coverage [COMPLETE]

• QuantTrade Beta Whitelist — Super Admin UI added to Platform Settings
• E-Signature Integration — PandaDoc + DocuSign affiliate connectors
• Unified Conversations — CRM-integrated WhatsApp, Email, and WebChat
• Client Approval Workflow — HITL UI for AI-generated marketing content
• UI Label i18n — Localized dashboard titles extracted to en.json

✅ Phase 6 — RBAC, Compliance & Advanced Moderation [COMPLETE]

• CRM Global Control Center — Cross-tenant visibility for Super Admin [DONE]
• Admin Impersonation Mode — "View as Tenant" for support [DONE]
• Automated Moderation (Sentinel):
  • Multimodal AI scanning for restricted goods/keywords. [DONE]
  • Moderation Worker: Real-time scanning of new content/products via BullMQ. [DONE]
• Feature Flags per Tenant — Per-client experimental toggles in Payload [DONE]
• System Banner Management — Platform-wide maintenance announcements [DONE]
• NLQ (Natural Language Query) — NL summaries for data tables [DONE]

✅ Phase 8 — Design Consistency & Branding [COMPLETE]

• Unified --primary to Indigo-Blue global identity.
• Removed all legacy violet-* brand colors and bg-gradient-* references.
• Standardized CRM, Marketing, and AI modules.

✅ Phase 10 — Saathi Personal CFO [COMPLETE]

• Financial Dashboard: AI-driven expense & subscription tracking UI. [DONE]
• Financial DB Schema: Extended Drizzle with bank connection tables. [DONE]
• AI Fiscal Intelligence: Integrated SaathiCategorizer and extraction. [DONE]
• Saathi Persistence: Implemented database save logic for extracted data. [DONE]

✅ Phase 7 — Advanced UI/UX & Intelligence [COMPLETE]

• Help Center RAG Bot: Platform-trained assistant for automated support. [DONE]
  • Vector Storage: Enable pgvector on Postgres and update Drizzle schema (document_embeddings). [DONE]
  • Ingestion Worker: BullMQ job to chunk and vectorize Payload CMS content and FAQS. [DONE]
  • Retrieval Engine: Add /api/brain/rag/query to FastAPI using semantic similarity search. [DONE]
  • Interface: Floating widget integration for clients with conversation history. [DONE]
• AI-Driven Insights: Added LLM Strategic Summaries to analytics. [DONE]
• Customizable Widgets: Implemented drag-and-drop overview dashboard. [DONE]
• Developer Sandbox: Created interactive API terminal. [DONE]
• Bulk Selection: Standardized Multi-select UI for CRM and Ecommerce. [DONE]
• Standardized UI: Generic BulkActionToolbar component. [DONE]
• CRM Bulk Actions: Mass Delete, Tag (JSONB), and Industry Assignment. [DONE]
• Ecommerce Bulk Cataloging: Group price adjustments and visibility toggles. [DONE]

✅ Phase 12 — Platform Intelligence & Health [COMPLETE]

• Command Palette (Ctrl+K): Unified global search + bulk actions via keyboard. [DONE]
• Moderation Transparency: Tenant-facing "Moderation Desk" to view flagging reasons. [DONE]
• System Health Dashboard: Real-time observability of BullMQ queues and API quotas. [DONE]
• Automated Workflow Registry: Dynamic mapping of BullMQ workers. [DONE]

✅ Phase 13 — Technical Debt & Partial Implementations [COMPLETE]

• Feature Orchestrator: Implemented configuration persistence and activation hooks. [DONE]
• Onboarding Service Persistence: Mapped industry context to PlatformSettings. [DONE]
• Workflow Governance: Connected BullMQ/Temporal pipelines and notification triggers. [DONE]
• Auth Context Resolution: Resolved Next.js/Authentik context in AI chat. [DONE]
• Base Agent Capabilities: Implemented multimodal stubs and enterprise connectors. [DONE]
• Temporal Executor: Created bridge service for production workflow orchestration. [DONE]
• Persona Security: Added system token validation for internal extraction APIs. [DONE]

🚀 Phase 20 — Advanced Observability & ROI [DONE]

• Visual Reasoning Graph: Implement interactive "Agent Thought Trace" in the Client Portal.
• Revenue Attribution: Link agent task completions to CRM conversion events.
• Agent ROI Dashboard: Real-time visualization of hours saved and revenue generated.

🚀 Phase 21 — Autonomous Governance [DONE]

• Emergency Kill-Switch: Implement tenant-level worker suspension in BullMQ and REST.
• Brand DNA Hub: Centralized UI in Payload CMS for managing brand voice and global system prompts.
• System Integrity: Finalized 401 MFA singleton auth pattern and cross-subdomain cookie handling.

🚀 Phase 15 — Launch Security & Threat Gating [COMPLETE]

• Core Encryption: Dynamic cross-subdomain authentication cookies, Argon2 secure hashing, and TOTP MFA session checks.
• Security Sentinel: Automated Phase 3 upgrade providing sliding window intrusion detection in Redis, active gateway inspect filters for sanitization, background security auditing, and a self-learning signature quarantine engine.
• Infrastructure Hardening: Hardened UFW firewalls locking down VPS ports to Cloudflare proxy edges, disabled host-level Nginx processes, locked SSH access to designated admin IPs, and rotated Dokploy master API secrets.

🚀 Phase 22 — Magic GTM Automation [COMPLETE]

• Programmatic GTM Connect: Dynamic container creation, trigger mapping, tag building, and version publishing via the Google Tag Manager Connector.
• GA4 Autopilot: Dynamic creation and provisioning of Google Analytics 4 tracking tags directly inside client GTM workspaces.
• Zero-Touch Onboarding: Integrated GTM automation into the magic onboarding background worker loop, linking discovered assets directly to the tenant's site configuration.

---

Support Hierarchy (4-Tier)

Tier	Role	Responsibility
Tier 1	Partner	First-line support for managed clients
Tier 4	Super Admin	Full system authority — emergency interventions

---

Verification Plan

1. PostHog Audit — Confirm all funnel events appear in dashboards.
2. Playwright E2E — Phase-by-phase regression testing.
3. Bulk Ops Verification: Test JSONB metadata tagging and Payload batch updates.
4. Governance Test: Simulate an agent "Panic" and verify worker suspension.