AI Visibility — Architecture

Database Schema

Models

AIVisibilityPlatform — global registry of supported LLM platforms (seeded, not tenant-editable):

TenantAIVisibilityPlatform — per-tenant platform toggle:

AIVisibilityPrompt — prompts monitored per tenant:

AIVisibilitySnapshot — one row per prompt × platform per run:

AIVisibilityNarrative — brand narrative generated after each run:

BullMQ Workers

agent__ai-visibility-monitor

File: packages/agents/src/workers/ai-visibility-monitor.worker.ts

Job data: AIVisibilityMonitorJobData — { tenantId, tenantName, promptIds? }

Flow:

1. Load globally enabled platforms, filter by tenant preferences and apiKeyEnvVar presence
2. Load active prompts for the tenant (all, or specific promptIds if provided)
3. Reserve ai_visibility credits
4. For each prompt × platform: call LLM, parse brand mentions + cited URLs + competitor names, write AIVisibilitySnapshot
5. Consume credits if any snapshots were created; release if none
6. Enqueue brand-narrative-analyst job after a successful run

LLM callers:

Nightly schedule: registered on worker startup, runs at 0 2 * * * UTC.

agent__brand-narrative-analyst

File: packages/agents/src/workers/brand-narrative-analyst.worker.ts

Auto-triggered after each monitor run. Reads the latest snapshots and produces a human-readable narrative (AIVisibilityNarrative) describing how the brand is perceived across AI platforms.

API Routes

All routes under /tenant/v1/ai-visibility in apps/api/src/routers/ai-visibility.ts. Require tenant JWT auth.

apiKeyPresent Check

Both the API and the Next.js dashboard server component check process.env[p.apiKeyEnvVar] to determine whether to show “API key missing”. This means the keys must be present in both apps/api/.env and apps/dashboard/.env.local even though the actual LLM calls only happen in apps/servers/agents/.env.

Three files must have the keys:

Seed Data

packages/db/src/seed.ts → seedAIVisibilityPlatforms() upserts the four platform records on every seed run. Re-run pnpm db:seed (from packages/db) after changing apiKeyEnvVar or model values.

Current seeded values: