Overview & Philosophy

F! Insights is a private, self-hosted intelligence engine for local business prospecting and GBP fulfillment. Unlike SaaS tools that charge per location, F! Insights runs on your server, your database, your rules.

The core strategy flips the dynamic of cold outreach: instead of interrupting with a claim, you provide a visitor with their own data and an AI-scored audit of exactly where they are losing ground to competitors. You aren't telling them they have a problem, Google's data is.

The Scan Report

Every scan produces an overall score out of 100 and individual scores across eight categories:

Requirements

• WordPress 6.2+
• PHP 8.0+ (required for modern string functions and named arguments)
• Google Cloud Project with billing enabled (Places, Maps, and GBP APIs)
• Anthropic API Key (Claude AI-powered analysis)

Installation

Technical Architecture

F! Insights is built for reliability and data sovereignty.

• Database: 19 tables managed via dbDelta(). Idempotent runtime upgrades ensure schema consistency without data loss.
• Uninstall: A "nuclear" uninstall option is provided, requiring explicit opt-in to wipe all tables, options, and logs.
• Rate Limiting: Fixed-window per IP with proxy and CDN detection to prevent API abuse.
• API Layer: All Claude calls route through FI_Claude::request() with automatic 429/529 retry handling and token tracking.
• Security: Stripe API keys are encrypted at rest with AES-256-CBC. All AJAX handlers use nonce verification and capability checks. Scan access tokens (short-lived transients) prevent cross-user report access.

API Configuration (Settings)

All core settings live under F! Insights → Settings → API Config.

Google API

Requires a Google Cloud project with the following APIs enabled:

• Places API (New): Core business data.
• Geocoding API: Lat/lng conversion.
• PageSpeed Insights API: Performance metrics.
• Maps JavaScript API: Geogrid ranking map.
• Google Business Profile API: Fulfillment features.

Claude API

Configure separate models for different tasks:

• Report Model: Claude Haiku 4.5 is recommended for scan-time analysis (fast, cost-effective, ~$0.01 per scan).
• Admin Intelligence Model: Claude Sonnet 4.5 or Opus 4 is recommended for Market Intel, Writing Campaign, and Near Me Visibility (higher quality).

Premium License

Enter your Polar.sh license key to activate premium features. The key is validated against the Polar API on save and stored locally. Features unlock immediately on validation.

GBP OAuth

Required for all fulfillment features (GBP Posts, Optimizer, Monitoring). Set up a Google Cloud OAuth 2.0 client ID and secret, then enter the redirect URI shown in the settings panel. Each client connects their own Google account via the connection widget in Client Workspace → Overview.

Stripe Billing

Connect your Stripe account to automate client billing. Enter your Stripe secret key (live or test). Map internal Client Plans to Stripe Price IDs. The plugin handles subscription lifecycle events (payment success, failure, cancellation) via webhooks.

Client Plans

Found under Settings → Stripe Billing → Client Plans. Define tiered service plans (e.g., Starter, Professional, Full Management) and map each to a Stripe Price ID. Plans gate feature access across the entire Client Workspace.

Each plan is a checklist of feature flags. When you enable a flag on a plan, all clients on that plan immediately gain access to the corresponding workspace tab or capability, with no page reload required. Disabling a flag removes it just as quickly.

Subscriptions & Billing

Client subscriptions are managed from Client Workspace → Overview → Subscription & Plan. The plugin supports two billing modes, giving you full flexibility regardless of how you invoice your clients.

Stripe Billing

When Stripe is connected and a Stripe Price ID is attached to the plan, activating a client via Stripe creates a subscription in your Stripe dashboard and charges the client automatically. Subscription state (active, past due, cancelled) is synced via webhooks: if a payment fails, feature access is automatically suspended until the issue is resolved.

External Billing

If you invoice clients directly (retainer, bank transfer, or any arrangement outside the plugin), use the External billing path. Feature access activates immediately, with no Stripe account required. Optionally set a renewal date and billing note (e.g., "Invoice #412, Net 30") for your own records.

When a renewal date is set, the plugin automatically expires the subscription when that date passes. A renewal action resets the date and re-activates access.

White Label

Found under F! Insights → Settings → White Label. Configure your agency name, logo, brand colors, and remove the F! Insights credit line from all client-facing reports. The report should feel like your proprietary software, not a third-party tool.

Notifications

Found under F! Insights → Settings → Notifications. Configure email alerts for new leads, follow-up reminders, and GBP monitoring events. Uses WordPress's native mail system (wp_mail). Pair with an SMTP plugin for reliable delivery.

Market Leads Page (fi-market-intel)

The primary operations hub for your agency. All prospecting, fulfillment, content, and planning tools live here across eight tabs.

Lead Form

Configure the public-facing scanner shortcode that visitors use to scan their Google Business Profile. Settings include the form headline, CTA button text, redirect URL after report delivery, and campaign-level overrides. Changes here affect every instance of

Leads & Prospects

Manage all contacts in your pipeline. Leads are visitors who scanned their own business via the shortcode. Prospects are businesses imported via Bulk Scan that have not yet engaged with you. Both types can be promoted to Client status, which makes them available in Client Workspace.

Actions available per row: view report, generate AI pitch, send email, promote to client, update status, and add notes. The Generate Prospect List widget at the top uses AI to find new businesses by category and location.

Bulk Scan

Run automated scans against a CSV list of businesses in the background via WP-Cron. Upload a file with business names and addresses, set a scan job running, and let it process asynchronously. The dashboard shows real-time progress, pass/fail counts, and token usage.

Supports pause, resume, per-item retry, and automatic recovery for items that get stuck in a scanning state. Completed results appear in the Leads & Prospects tab as Prospects.

Analytics

An interpretive briefing of your lead pipeline. Insight panels unlock progressively as your scan volume grows (10, 25, 50, 100, 250 scan thresholds). Includes score distribution, category gap patterns, and pipeline health metrics. Use this to identify which vertical or location has the most underperforming profiles, informing where to focus outreach.

Market Intel

AI-powered competitive and market analysis generated from your accumulated scan data. Produces industry-specific reports on profile quality gaps, common weaknesses, and optimization opportunities across your pipeline. Reports are cached and regenerated as your scan volume grows.

Includes a Pitch Generator that crafts outreach emails using the specific gaps from a lead's scan, replacing generic cold messages with data-backed observations the prospect can verify for themselves.

Viz Beta

A public-facing data visualization layer that publishes aggregated scan data as embeddable D3.js charts. The core SEO strategy: third-party sites that embed your charts link back to your hub page with a contextual attribution link, turning your scan database into a passive backlink engine.

Visualization modules

REST endpoints

Shortcodes

Client Workspace Beta

The unified fulfillment hub. Select a client from the dropdown to open their workspace. All sub-tabs operate in that client's context. The selector bar shows GBP connection status, current plan, and subscription state at a glance.

Writing Campaign Beta

A keyword-first content sprint engine. Enter a focus keyword and get a prioritized article queue split across funnel stages: 60% BoFu (bottom-of-funnel, high-intent), 20% MoFu, and 20% ToFu. Each article is generated by Claude with SEO-anchored titles and funnel-appropriate framing.

Road Map

A kanban board showing the current development state of F! Insights. Three columns: Shipped (last 10 released features), In Progress (currently in development), and Up Next (planned backlog). The Road Map tab is always the last tab in Market Leads.

Reviews Setup

Found inside Client Workspace → Reviews Setup. Provides a complete review collection kit per client: a review snippet (embeddable widget for the business website), a printable QR code, a branded email template for outreach, and a running review count tracker.

All assets are generated per client and can be re-generated at any time. The QR code links directly to the client's Google review submission URL.

Map Pack (Geogrid)

Found inside Client Workspace → Map Pack. Run a geogrid ranking scan for the client's business and target keyword. The result is a heatmap showing position 1-20 across a configurable grid of points radiating from the business location.

After a successful scan, a Build Visibility Plan button appears that takes you directly to the Near Me Visibility tab with the scan result pre-loaded as the input for the action plan.

Near Me Visibility

Found inside Client Workspace → Near Me Visibility. Builds a 5-pillar action plan from the client's most recent Map Pack scan:

1. GBP-Web Alignment: NAP consistency between GBP and website.
2. Hyper-Local Content: Neighborhood and service-area content gaps.
3. Attribute Gap Analysis: Missing category-specific GBP attributes.
4. Authority Signals: Citation gaps, link opportunities, and trust factors.
5. Review Velocity: Review frequency, recency, and response patterns.

Each pillar outputs a prioritized list of actions with difficulty and impact ratings. This plan is designed to be handed directly to the client as a Phase 1 deliverable.

GBP Profile Optimizer

Found inside Client Workspace → Optimizer. A 6-item completeness checklist that audits the client's GBP profile against Google quality signals. For each gap, Claude generates an optimized replacement (description, categories, attributes, services) that can be pushed directly to Google with one click, without the client needing to log in.

Service Pages

Found inside Client Workspace → Service Pages. Generates AI-written, SEO-optimized service area pages and publishes them as WordPress draft posts for review before going live. Page count is gated by plan: 10 pages on Professional, 30 pages on Full Management.

Each page is built around a target keyword, includes schema-ready content, and is linked to the client record via post meta for tracking.

Ranking Dashboard

Found inside Client Workspace → Rankings. A 6-panel performance overview showing score history with month-over-month and year-over-year deltas, geogrid ranking progression, category-level trend lines, and a comparison against the client's baseline scan. Designed to be shared with the client as a retention-focused monthly check-in.

Debug Logs

Found under F! Insights → Debug Logs. Structured logs for all API calls, scan runs, cron events, and errors. Log files rotate daily and are stored in /wp-content/fi-insights-logs/. Most production issues are either expired API keys or Google Cloud billing limits, both visible immediately in the error log.

Optimization Guide: Maximizing F! Insights

Follow these steps to turn the plugin into a high-performance agency engine.

1. Foundation & Configuration

2. Prospecting & Lead Gen

3. Onboarding & Fulfillment

4. Management & Retention

5. Debug & Maintenance

Shortcodes

Roadmap & Changelog

Planned

• Billing source toggle on existing subscriptions (switch between Stripe and External from the Overview tab).
• Review monitoring: real-time detection and alerts for new Google reviews.
• Booking/menu URL sync: direct push to GBP Optimizer from the service setup screen.