Skip to main content

BizOSaaS Platform — Essential File Reference Map

Purpose: Zero-search reference for all critical files, folders, and configurations.
Updated: 2026-07-15
Use this file FIRST before performing any grep/find operations to save LLM tokens.

📁 Monorepo Root​

/media/alagirirajesh/storage/projects/bizosaas-platform/
├── apps/
│   ├── web/          → Next.js 16 multi-tenant app (client + admin + partner portals)
│   ├── workers/      → BullMQ background workers (TypeScript)
│   ├── ai-service/   → Python FastAPI AI agent service
│   ├── docs/         → Docusaurus documentation site
│   └── e2e/          → Playwright E2E test suite
├── packages/
│   ├── db/           → Drizzle ORM shared DB package
│   ├── ui/           → Shared shadcn/ui components
│   ├── config/       → Shared ESLint, TSConfig, Tailwind config
│   └── testing/      → Shared test utilities
├── infrastructure/   → Docker Compose, Caddy, deployment scripts
└── package.json      → Root pnpm workspace config

🗄️ Database Schema​

FilePurpose
packages/db/src/schema/core.tsPRIMARY SCHEMA — all tables: tenants, users, contacts, deals, campaigns, agentTaskLog, conversations, messages, subscriptions, etc. (1567 lines)
packages/db/src/schema/crm.tsCRM-specific tables: crmActivities, crmMetricSnapshots, crmPipelines, crmPipelineStages
packages/db/src/schema/pages.tsPayload CMS Pages table
packages/db/src/schema/partner-alerts.tspartnerAlertPreferences, userAlertPreferences, consequenceWarnings
packages/db/src/index.tsDB client exports — getAuthDb(), withTenant(), all table refs

Key Tables (in core.ts)​

TableLocation (line)Description
tenants~4Multi-tenant anchor — every row is scoped by tenantId
user~53Auth users (better-auth native)
contacts~351CRM contacts — firstName, lastName, email, status, leadScore
deals~379CRM deals — amount, stage, probability
campaigns~425Marketing campaigns — platform, spend, revenue, conversions
agentTaskLog~670BullMQ task telemetry — status, progress (0-100), workerName
agentMilestoneLog~703Granular agent milestone events
conversations~521Inbox conversations — platform, participantName, lastMessageAt
messages~541Individual messages per conversation
subscriptions~201Stripe/Razorpay subscriptions — gateway, status, plan
invoices~224Invoice records
crmTeams~892CRM teams — name, description
crmTeamMembers~909Team-user pivot — teamId, userId, role
crmWorkflows~980CRM workflow definitions
auditLogs~1127Immutable compliance/security audit log
connectorSecrets~1480OAuth tokens per tenant per connector
partnerManagedTenants~86Partner→Client relationships
tenantIntegrations~779Integration config per tenant (Shopify, Gmail, etc.)
supportTickets~631Support ticket system
agentTaskLog~670Real-time agent task progress (source of truth for all progress bars)

🌐 Web App Structure (apps/web/src/)​

Key Library Files​

FilePurpose
lib/auth.tsBetter-Auth configuration + session helpers
lib/tenant.tsgetEffectiveTenantId(), getTenantIdByHost()
lib/format.tsformatCurrency() and other formatters
lib/cms/api.tsgetPayloadClient(), getTenantProducts(), getPlatformSettings()
lib/cms/products.tsPayload product fetch helpers
lib/billing/Billing helpers
lib/actions/ai-actions.tsServer actions for AI endpoints
lib/actions/cms-actions.tsServer actions for Payload CMS mutations

Authentication​

FilePurpose
middleware.tsMulti-tenant routing + auth guards (subdomain detection)
app/api/auth/[...all]/route.tsBetter-Auth catch-all handler

Admin Portal (app/(admin)/admin/)​

RouteFilePurpose
/adminpage.tsxAdmin overview dashboard
/admin/tenantstenants/page.tsxTenant management
/admin/billingbilling/page.tsxAdmin billing overview
/admin/billing/gatewaysbilling/gateways/page.tsxPayment gateway config
/admin/economicseconomics/page.tsxPlatform economics / BizCredits
/admin/marketplacemarketplace/page.tsxAdd-ons marketplace
/admin/ai-agentsai-agents/page.tsxAI agent fleet management
/admin/ai-agents/actions.ts—Agent task server actions
/admin/observability/agentsagents/page.tsxAgent observatory
/admin/observability/agents/actions.ts—Observability server actions
/admin/inboxinbox/page.tsxUnified inbox
/admin/inbox/actions.ts—fetchInboxConversations(), fetchInboxStats(), sendReply()
/admin/crm/broadcastsbroadcasts/page.tsxCRM broadcast campaigns
/admin/moderationmoderation/actions.tsContent moderation actions
/admin/infrastructureinfrastructure/page.tsxServer health metrics
/admin/analyticsanalytics/page.tsxPlatform analytics charts
/admin/ecommerce/policypolicy/actions.tsE-commerce policy management

Client Dashboard (app/(dashboard)/dashboard/)​

RouteFilePurpose
/dashboardpage.tsxMain client overview
/dashboard/crmcrm/page.tsxCRM overview
/dashboard/crm/contactscrm/contacts/page.tsxContacts list
/dashboard/crm/dealscrm/deals/page.tsxDeals pipeline
/dashboard/crm/teamscrm/teams/page.tsxTeams list (loads real members via DB join)
/dashboard/crm/teamscrm/teams/TeamsClient.tsxTeams UI (renders real member avatars)
/dashboard/crm/workflowscrm/workflows/page.tsxWorkflow builder
/dashboard/crm/workflowscrm/workflows/WorkflowsClient.tsxWorkflow UI (real executionCount from DB)
/dashboard/billingbilling/page.tsxClient billing/subscription page
/dashboard/ecommerce/syncecommerce/sync/page.tsxEcommerce sync pipelines (live from agentTaskLog)
/dashboard/ecommerce/productsecommerce/products/page.tsxLive product catalog (from Payload CMS)
/dashboard/partner/compliancepartner/compliance/page.tsxGDPR/DSAR portal
/dashboard/partner/snapshotspartner/snapshots/page.tsxPartner snapshot deployments
/dashboard/partner/leaderboardpartner/leaderboard/page.tsxPartner performance leaderboard
/dashboard/marketing/campaignsmarketing/campaigns/page.tsxCampaign management
/dashboard/marketing/campaigns/marketplacemarketplace/page.tsxCampaign marketplace
/dashboard/brandingbranding/page.tsxWhite-label branding settings
/dashboard/branding/actions.ts—Branding server actions
/dashboard/rewardsrewards/page.tsxRewards program
/dashboard/rewards/redeemrewards/redeem/page.tsxRedeem rewards
/dashboard/settings/billingsettings/billing/page.tsxSettings billing tab
/dashboard/settings/billing/actions.ts—Billing server actions
/dashboard/activityactivity/page.tsxAI activity log history

Partner Portal (app/(partner)/partner/ and /dashboard/partner/)​

RouteFilePurpose
/partnerpage.tsxPartner overview
/partner/clientsclients/page.tsxClient management
/partner/taskstasks/page.tsxPartner task management
/partner/approvalsapprovals/page.tsxApproval center
/partner/revenuerevenue/page.tsxPartner revenue tracking
/partner/supportsupport/page.tsxCross-client support view
/partner/alertsalerts/page.tsxAlert management
/partner/policiespolicies/page.tsxPolicy management

API Routes (app/api/)​

RouteFilePurpose
/api/auth/[...all]auth/[...all]/route.tsBetter-Auth handler
/api/ai/briefingai/briefing/route.tsAI daily briefing (real agentTaskLog progress)
/api/ai/billing/plansai/billing/plans/route.tsSubscription plans
/api/ai/billing/subscriptionai/billing/subscription/route.tsActive subscription
/api/ai/billing/invoicesai/billing/invoices/route.tsInvoice history
/api/tenants/usagetenants/usage/route.tsUsage metrics (AI credits, CRM contacts, messages)
/api/tenants/payment-methodtenants/payment-method/route.tsPayment method info
/api/agent-tasks/streamagent-tasks/stream/route.tsSSE real-time task feed
/api/agent-tasksagent-tasks/route.tsTask history REST endpoint
/api/ecommerce/sync/pipelinesecommerce/sync/pipelines/route.tsLive sync pipeline status (agentTaskLog)
/api/ecommerce/sync/inventoryecommerce/sync/inventory/route.tsInventory sync trigger
/api/ecommerce/sync/conflictsecommerce/sync/conflicts/route.tsConflict detection
/api/partner/clientspartner/clients/route.tsPartner's managed clients list
/api/partner/compliancepartner/compliance/route.tsGDPR export/deletion across tenants
/api/partner/leaderboardpartner/leaderboard/route.tsPartner rankings from DB
/api/partner/snapshotspartner/snapshots/route.tsSnapshot deployment endpoint
/api/analytics/channel-performanceanalytics/channel-performance/route.tsNEW Live ROAS by channel from campaigns table
/api/analytics/social-proofanalytics/social-proof/route.tsNEW Live social proof events from contacts
/api/templatestemplates/route.tsNEW Templates from Payload CMS
/api/onboarding/magiconboarding/magic/route.tsMagic onboarding endpoint
/api/checkoutcheckout/route.tsStripe checkout session

Dashboard UI Components (components/dashboard/)​

ComponentFilePurpose
AgentActivityFeedAgentActivityFeed.tsxReal-time SSE task feed widget
SocialProofWidgetSocialProofWidget.tsxLive events from /api/analytics/social-proof
TemplateMarketplaceTemplateMarketplace.tsxLive from /api/templates with search/filter
VideoReviewWidgetVideoReviewWidget.tsxVideo testimonials display

Ecommerce Components (components/ecommerce/)​

ComponentFilePurpose
ChannelROASChartChannelROASChart.tsxLive channel ROAS from /api/analytics/channel-performance

Providers (components/providers/)​

ComponentPurpose
tenant-preferences-provider.tsxCurrency, locale preferences from DB

⚡ Workers (apps/workers/src/)​

FilePurpose
index.tsMain entrypoint — bootstraps all workers
content.worker.tsContent generation tasks
email.worker.tsEmail sending + campaign tasks
seo.worker.tsSEO audit + keyword research tasks
social-media.worker.tsSocial posting + scheduling
billing.worker.tsInvoice + subscription sync
analytics.worker.tsAnalytics sync
discovery.worker.tsSilent discovery + competitor analysis
domain.worker.tsDomain assignment + expiry checks
agent-task.worker.tsGeneric AI agent tasks
onboarding.worker.tsTenant provisioning
reporting.worker.tsAutomated ROI reports
lib/task-log.tsShared logTaskStart(), logTaskProgress(), logTaskComplete(), logTaskFail()

🤖 AI Service (apps/ai-service/app/)​

PathPurpose
api/FastAPI route handlers
api/support.pySupport ticket AI auto-triage
agents/CrewAI agent definitions (28+ agents)
connectors/74+ external service connectors
connectors/erpnext.pyERPNext connector
connectors/cloudflare.pyCloudflare DNS + zone management
services/Business logic services
services/billing_service.pyStripe/Razorpay billing + usage metering
services/usage_manager.pyRedis-based usage quota management
services/support_email.pySupport email + multilingual detection
models/SQLAlchemy models

🧪 E2E Tests (apps/e2e/)​

FilePurpose
playwright.config.tsPlaywright config — base URLs for all portals
tests/helpers/e2e.config.tsTest environment config (IP, subdomain URLs)
tests/01-auth.spec.tsAuth flow tests
tests/02-onboarding.spec.tsOnboarding flow tests
tests/03-dashboard-routes.spec.tsDashboard routing tests
tests/04-crm.spec.tsCRM feature tests
tests/admin/Admin portal test suite
tests/partner/Partner portal test suite

Test URLs (Local)​

  • Admin: http://admin.bizoholic.local:3000
  • Partner: http://partner.bizoholic.local:3000
  • Client: http://app.bizoholic.local:3000 or http://coreldove.bizoholic.local:3000

🐳 Infrastructure​

FilePurpose
infrastructure/docker-compose.ymlMain production compose — web, ai-service, workers, postgres, redis
infrastructure/docker-compose.dev.ymlLocal dev compose
infrastructure/scripts/deploy.shProduction deploy script
infrastructure/scripts/migrate.shDatabase migration script
infrastructure/scripts/seed.shDatabase seed script
infrastructure/configs/Caddy, OTel collector configs

📦 Key npm Scripts​

# From monorepo root:
pnpm dev                    # Start all apps in dev mode
pnpm build                  # Build all apps
pnpm --filter web build     # Build only web app
pnpm --filter e2e test      # Run all E2E tests
pnpm --filter e2e test:admin  # Run only admin E2E tests
pnpm --filter e2e test:partner # Run only partner E2E tests
pnpm lint                   # Lint all workspaces
pnpm typecheck              # Type check all workspaces

# DB Operations (from monorepo root):
pnpm --filter @bizosaas/db generate  # Generate Drizzle migrations
pnpm --filter @bizosaas/db migrate   # Apply migrations to DB
pnpm --filter @bizosaas/db seed      # Seed initial data

🔑 Environment Variables (via Infisical)​

Secrets are fetched from app.infisical.com. Key env vars:

VariablePurpose
DATABASE_URLPostgreSQL connection string
REDIS_URLRedis connection for BullMQ
BETTER_AUTH_SECRETAuth session signing secret
NEXT_PUBLIC_APP_URLBase app URL
OPENROUTER_API_KEYAll LLM calls (OpenAI, Anthropic via OpenRouter)
STRIPE_SECRET_KEYStripe payments
RAZORPAY_KEY_ID/SECRETRazorpay (India) payments
PADDLE_API_KEYPaddle (MoR for partner marketplace)
RESEND_API_KEYEmail sending
ELEVENLABS_API_KEYTTS / Voice agents
CLOUDFLARE_API_TOKENDNS management
PAYLOAD_SECRETPayload CMS admin secret
AI_SERVICE_URLInternal FastAPI service URL

Note: No separate OpenAI/Anthropic keys needed — use OPENROUTER_API_KEY for all LLMs.

🌐 Production URLs​

PortalURL
Main Apphttps://app.bizoholic.com
Admin Portalhttps://admin.bizoholic.com
Partner Portalhttps://partner.bizoholic.com
Client Site Examplehttps://coreldove.bizoholic.com
Docshttps://docs.bizoholic.com
AI ServiceInternal (not public)

📊 Mock Data Removal Status (2026-07-15)​

All items below have been fully replaced with live database queries:

ComponentOld MockNew Live Source
ChannelROASChart.tsxMOCK_CHANNELS[]/api/analytics/channel-performance → campaigns table
TemplateMarketplace.tsxMOCK_TEMPLATES[]/api/templates → Payload CMS templates collection
SocialProofWidget.tsxMOCK_EVENTS[] + Math.random()/api/analytics/social-proof → contacts table
TeamsClient.tsxMath.random() initialscrmTeamMembers JOIN user (real initials)
WorkflowsClient.tsxMath.random() * executionsworkflow.executionCount from DB
ecommerce/sync/page.tsxMOCK_SYNCS[], MOCK_CONFLICTS[]/api/ecommerce/sync/pipelines → agentTaskLog
api/ai/briefing/route.tsMath.floor(Math.random() * 30)t.progress from agentTaskLog
admin/inbox/actions.tsHardcoded stats (12, 87, etc.)Live count queries with 24h window filter
/ecommerce/products/page.tsxMOCK_PRODUCTS[]Redirect to /dashboard/ecommerce/products (Payload CMS)
partner/compliance/page.tsxStatic DSAR UILive cross-tenant contact search + audit log
partner/leaderboard/page.tsxHardcoded rankings/api/partner/leaderboard → partnerManagedTenants + agentTaskLog
partner/snapshots/page.tsxStatic snapshot list/api/partner/clients → real managed clients

Remaining Stubs (intentional/acceptable)​

ComponentStatusNotes
VideoReviewWidget.tsxHardcoded 2 reviewsAcceptable until client uploads real video testimonials
finance/actions.tsStubbedPlaid/Razorpay ledger integration pending
Briefing API progress✅ FixedNow uses real agentTaskLog.progress

📋 Docs & Plans Files​

FilePurpose
apps/docs/docs/tasks/rebuild-tasks.mdMaster task tracker — all phases + completion status
apps/docs/docs/plans/implementation-plan.mdDetailed implementation plan
apps/docs/docs/plans/platform-file-map.mdTHIS FILE — zero-search quick reference
apps/docs/docs/roadmap.mdProduct roadmap

🔗 Git & CI/CD​

ItemValue
RepoBizoholic-Digital/bizosaas-platform
Main branchmain
CI workflow.github/workflows/ci.yml
Deploy workflow.github/workflows/deploy.yml
Container registryGHCR (GitHub Container Registry)

🏗️ Active Clients (Tenants)​

ClientSlugStatus
Coreldove D2Ccoreldove✅ Onboarded, dashboard active
Thrillring (Gaming)thrillring✅ Internal test client
QuantTradequanttrade✅ Internal test client
Saathi CFOsaathi🔄 Email intelligence pivot

Last updated: 2026-07-15 — Generated after mock data purge sprint