Documentation

1. SEND PROMPT TO AI MODEL
   ├─ Send industry-relevant query to configured AI model
   ├─ API Calls to configured models: Response model answers the prompt
   └─ Returns full response text + cited sources/URLs

2. EXTRACT URLS FROM RESPONSE
   ├─ Parse any URLs the AI cited in its response
   └─ Fetch page metadata (title, description) for each URL

3. ANALYZE RESPONSE FOR MENTIONS
   ├─ API Calls GPT-4o-mini to analyze the response via mention-analysis prompt
   └─ This detects:
      ├─ Was your brand mentioned?
      ├─ What position in rankings? (1st, 2nd, 3rd...)
      ├─ Which competitors were mentioned?
      ├─ Sentiment (positive/neutral/negative)
      └─ Source types (editorial, UGC, reference, etc.)

4. CALCULATE & STORE
   ├─ Calculate visibility score and share of voice
   ├─ Save results to database
   └─ Update dashboard in real-time

1. QUERY EXECUTION DATA
   ├─ Get all prompt executions from database for date range
   └─ Each execution has: business_visibility, competitor_visibilities,
      mention_analysis (position, sentiment)

2. CALCULATE VISIBILITY SCORES
   ├─ Business visibility = (executions with brand mentioned / total) × 100
   ├─ Competitor visibility = (executions with competitor mentioned / total) × 100
   └─ Store per-platform breakdown for model comparison

3. EXTRACT POSITION & SENTIMENT
   ├─ Parse mention_analysis JSON from each execution
   ├─ Position = brandPosition field (1st, 2nd, 3rd...)
   ├─ Sentiment = brandSentiment or brandSentimentScore (0-100)
   └─ Average across all executions where brand appeared

4. CALCULATE PERIOD-OVER-PERIOD CHANGES
   ├─ Query previous period (same duration, before start date)
   ├─ Compare visibility, sentiment, position
   └─ Return change values (e.g., +5.2%, -1 position)

1. QUERY EXECUTION DATA
   ├─ Get all prompts and executions from database
   ├─ Each execution has: brand_mentions (0 or 1),
   │  competitors_mentioned (JSON array), sources (JSON array)
   └─ Group executions by prompt_id

2. IDENTIFY CONTENT GAPS
   ├─ For each prompt, count: brandWins (brand_mentions > 0)
   ├─ Count: competitorWins (competitors_mentioned.length > 0)
   ├─ If competitorWins > brandWins → create content gap
   ├─ yourVisibility = (brandWins / totalExecutions) × 100
   ├─ competitorVisibility = (competitorWins / totalExecutions) × 100
   └─ Track which competitors are winning and sources they cite

3. DETECT SEGMENTS (regex pattern matching)
   ├─ Industry: /law firm|legal/ → "Law Firms"
   │            /healthcare|medical/ → "Healthcare"
   │            /e-commerce|retail/ → "E-commerce"
   │            /saas|software|cloud/ → "SaaS"
   ├─ Use-case: /remote team|work from home/ → "Remote Teams"
   │            /small business|startup/ → "Small Business"
   │            /enterprise|corporation/ → "Enterprise"
   └─ Persona:  /developer|engineer/ → "Developers"
                /marketer|marketing/ → "Marketers"
                /sales|salesperson/ → "Sales Teams"

4. EXTRACT TARGET KEYWORDS
   ├─ Split prompt text into words
   ├─ Filter stop words: the, a, what, how, best, for, to, in, of, and, or
   ├─ Keep words longer than 3 characters
   ├─ Capitalize first letter, return up to 5 keywords
   └─ Example: "best CRM tools for startups" → ["Crm", "Tools", "Startups"]

5. SUGGEST CONTENT TYPE (keyword matching)
   ├─ "compare" or "vs" → Comparison guide
   ├─ "how to" → Step-by-step tutorial
   ├─ "best" or "top" → Listicle or roundup
   ├─ "review" → In-depth review
   └─ "price" or "cost" → Pricing guide

6. CALCULATE & PRIORITIZE
   ├─ Gap score = (competitorVisibility - yourVisibility) × 0.5
   │              + competitorsWinning.length × 10 + totalExecutions × 2
   ├─ Estimated impact = gap score (capped at 100)
   └─ Sort all recommendations by impact (highest first)

1. EXTRACT SOURCES FROM EXECUTIONS
   ├─ Query all executions from database
   ├─ Each execution has sources JSON: [{domain, url, type}, ...]
   ├─ For each source, track per domain:
   │    frequency: how many times this domain appears
   │    brandPresent: count of executions where brand was also mentioned
   │    competitorPresent: count where competitors were mentioned
   │    promptsAppearing: which prompts cited this source
   │    urls: list of specific URLs cited
   └─ Skip your own domain (business.website)

2. CATEGORIZE SOURCES BY TYPE (domain pattern matching)
   ├─ UGC patterns: reddit.com, quora.com, facebook.com, twitter.com,
   │               x.com, linkedin.com, medium.com, dev.to,
   │               stackoverflow.com, *discourse*, *forum*,
   │               *community*, *groups*, *discuss*
   ├─ Reference patterns: wikipedia.org, britannica.com, *.gov,
   │                     *.edu, *.org, statista.com, *pew*,
   │                     *research*, *institute*, *foundation*
   ├─ Competitor: domain contains competitor name or website
   │             (matched against competitor list from database)
   └─ Editorial: everything else (news, blogs, publications)

3. CALCULATE PRIORITY SCORES
   ├─ Higher score = higher priority opportunity
   ├─ Editorial score = frequency × 5
   │                    + (100 - brandPresenceRate) × 0.3
   │                    + competitorPresenceRate × 0.5
   ├─ UGC score = frequency × 4
   │              + (100 - brandPresenceRate) × 0.4
   │              + competitorPresenceRate × 0.6
   ├─ Reference score = frequency × 6
   │                    + (100 - brandPresenceRate) × 0.2
   │                    + competitorPresenceRate × 0.3
   └─ brandPresenceRate = (brandPresent / frequency) × 100

4. GENERATE OUTREACH RECOMMENDATIONS
   ├─ Editorial actions based on brand presence:
   │    0% + competitor > 50% → "High-priority PR outreach"
   │    0% → "Pitch for inclusion in articles"
   │    < competitor → "Increase presence via guest posts"
   ├─ UGC engagement strategies by platform:
   │    Reddit → "Answer questions authentically, avoid self-promotion"
   │    LinkedIn → "Share thought leadership, engage discussions"
   │    Quora → "Answer thoroughly with data and examples"
   │    Stack Overflow → "Provide detailed technical answers"
   └─ Pitch types based on domain:
        techcrunch/venturebeat/wired → "Tech industry story"
        forbes/inc/entrepreneur → "Business/leadership angle"
        *review*/pcmag/cnet → "Product review or comparison"

5. PRIORITIZE & SORT
   ├─ Estimated impact = priority score × multiplier (capped at 100)
   │    Editorial: × 1.5, UGC: × 1.2, Reference: × 2.0
   └─ Sort all targets by estimated impact (highest first)

1. DISCOVER URLS
   ├─ Try sitemap.xml, sitemap_index.xml, sitemap/sitemap.xml
   ├─ If no sitemap: crawl homepage and extract internal links
   └─ Limit to 50 pages per audit

2. FETCH EACH PAGE (HTTP request)
   ├─ GET request with PromptClarity User-Agent
   ├─ 30 second timeout per page
   └─ Record load time in milliseconds

3. PARSE HTML (using node-html-parser)
   ├─ Extract: title, meta description, headings (H1-H6)
   ├─ Find schema markup: JSON-LD scripts → extract @type
   ├─ Count: words, lists, tables, images, links
   └─ Check: Q&A format, canonical URL, robots meta

4. CALCULATE SCORES (0-100)
   ├─ Structure: title + meta + H1 count + heading hierarchy
   ├─ Content: word count + Q&A format + lists + images with alt
   ├─ Technical: load time + schema count + canonical + robots
   └─ Overall: average of structure, content, technical

5. GENERATE ISSUES & RECOMMENDATIONS
   ├─ Issues: missing title, no H1, thin content, slow load
   └─ Recommendations: add FAQ schema, improve headings, add lists

Structure Score (100 points):
  Title present (15) + optimal length 30-60 chars (+10)
  Meta description present (15) + optimal length 70-160 chars (+10)
  Exactly one H1 (20) + H2 headings present (+10) + H3 present (+5)
  Proper heading hierarchy H1>H2>H3 (+15)

Content Score (100 points):
  Word count: 1500+ (30), 1000+ (25), 500+ (20), 300+ (10)
  Q&A format detected (+25)
  Has lists (+10) + has tables (+5)
  Internal links 5+ (15), 2+ (10), 1+ (5)
  Images with alt text (up to 15 based on ratio)

Technical Score (100 points):
  Load time: <1s (35), <2s (30), <3s (20), <5s (10)
  Schema types: 3+ (35), 2+ (30), 1+ (20)
  Has canonical URL (+15)
  Not blocking with noindex (+15)

Known AI crawlers to allow in robots.txt:

User-agent: GPTBot          # OpenAI
User-agent: ChatGPT-User    # ChatGPT browse mode
User-agent: Google-Extended # Gemini training
User-agent: anthropic-ai    # Claude
User-agent: PerplexityBot   # Perplexity
User-agent: Bytespider      # TikTok/ByteDance AI

Recommended robots.txt:
Allow: /
Allow: /docs/
Allow: /blog/
Allow: /products/

Daily at 2 AM UTC
       ↓
Trigger /api/cron/daily-executions
       ↓
For each business:
  ├─ Get all prompts
  ├─ Get all configured platforms
  ├─ Execute prompts (max 5 concurrent)
  └─ Store results with today's date
       ↓
Dashboard updates with new data points

{
  "crons": [{
    "path": "/api/cron/daily-executions",
    "schedule": "0 2 * * *"
  }]
}

POST https://your-domain.com/api/cron/daily-executions
Authorization: Bearer YOUR_CRON_SECRET

// Frontend usage
const eventSource = new EventSource('/api/prompts/executions/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Updates: {status: 'started'|'completed', promptId, ...}
  updateUI(data);
};

npm run build
npm start

docker run -d \
  --name prompt-clarity \
  -p 3000:3000 \
  -v prompt-clarity-data:/app/data \
  promptclarity/promptclarity:latest

docker pull promptclarity/promptclarity:latest
docker stop prompt-clarity && docker rm prompt-clarity
# Re-run the docker run command above

docker build -t prompt-clarity .
docker run -d -p 3000:3000 -v prompt-clarity-data:/app/data prompt-clarity

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Launch (creates fly.toml)
fly launch

# Set secrets
fly secrets set NEXTAUTH_SECRET="your-secret" NEXTAUTH_URL="https://your-app.fly.dev"

# Deploy
fly deploy